diff --git a/docs/handoff/2026-04-25-linux-to-windows.md b/docs/handoff/2026-04-25-linux-to-windows.md new file mode 100644 index 0000000..35e3ad9 --- /dev/null +++ b/docs/handoff/2026-04-25-linux-to-windows.md @@ -0,0 +1,188 @@ +# Session Handoff — Linux → Windows + +**Date:** 2026-04-25 +**Source:** Linux dev machine (Claude Code session) +**Target:** Windows dogfood machine (fresh Claude Code session) +**Reason:** Windows is the dogfood-priority platform (per spec §1.1). Implementation/test cycle should run there. + +--- + +## TL;DR for the next session + +Read these files first, in this order: + +1. `inkling.md` — original product brief (v1.4) +2. `docs/superpowers/strategy/strategy.md` — psychology-based habit strategy +3. `docs/superpowers/specs/2026-04-24-inkling-vertical-slice-design.md` — **spec v0.2** (load-bearing) +4. `docs/superpowers/plans/2026-04-24-inkling-vertical-slice.md` — **implementation plan v0.2** (33 tasks, TDD) +5. This handoff doc + +Then ask the user: "Spec v0.2 and plan v0.2 are committed but not yet implemented. Want me to start Task 1 (project bootstrap), or pick up from a specific task?" + +The project is a git repo with 7 commits. No application code written yet. Slice is 33 TDD tasks ahead. + +--- + +## What was decided (chronologically) + +The Linux session ran `/brainstorming` twice and `/writing-plans` once. Each decision below was made jointly with the user. Don't relitigate. + +### Brainstorming round 1 (initial slice scope) + +Q1: **Vertical slice approach** chosen over foundation-first or UI-shell-first. Goal is a single end-to-end path: Quick Capture → SQLite → Local Ollama → Inbox. Reason: only this proves both core hypotheses (3-second capture friction, AI quality). + +Q2: **Text + screenshot input** in slice. Voice/STT deferred to follow-up. + +Q3: **Both Windows + macOS Electron from day 1**, with **Windows as dogfood priority** and macOS as build-passing-only. Tech stack already locked by spec §6.2: Electron + React + TypeScript. + +Q4: **AI scope = title + 3-line summary + ≤3 tags.** Related-notes link and project classification deferred. + +Q5: **Inbox = list + AI-field edit + delete.** Original always read-only. Manual AI re-process deferred. + +Q6: **Habit engine = streak display only, no notifications**, in slice v0.1. Later upgraded in round 2 to Weekly Continuity (see below). + +User then said "잘 따라옴, 작성해" → spec v0.1 written. + +### Strategy doc shows up + +User added `docs/superpowers/strategy/strategy.md` and said "매우 중요한 스펙들을 놓쳤어" → re-ran `/brainstorming` for Strategy integration. + +### Brainstorming round 2 (Strategy integration) + +Q1: **Group-A items in slice** (UX copy, post-submit reward toast, AI proposal labels, 5 product principles, recovery-friendly streak copy) + **Group-B partial** (one-line intent question, Weekly Continuity). Templates and onboarding deferred. + +Q2: **Intent question = AI-done banner with skip option.** Variant A chosen. Stored in `notes.user_intent`, gated by `notes.intent_prompted_at`. + +Q3: **Weekly Continuity = KST 월~일, target N건/주.** Initially proposed 3, user **bumped to 7**. Recovery toast on ≥7-day gap. Streak Freeze deferred. + +Q4: **AI proposal label = per-field gray "AI" badge.** Disappears once `*_edited_by_user` flag flips. Tag source already distinguished. Schema columns added. + +Q5: **All copy strings + tray menu copy + 5 product principles in spec §0.1 + native OS notification for reward toast.** Recovery-friendly tone enforced ("실패", "끊김", "연속 실패" forbidden). + +Spec v0.2 + plan v0.2 then committed. + +--- + +## User profile (carry into memory on Windows) + +- **Name:** 김태현 (dlsrks0734@gmail.com) +- **Role:** IT 기획자, the persona in `inkling.md` §2.2. Building this app for himself first, then 10-person internal beta. +- **Language:** Speaks Korean. All product copy and AI output target Korean. Tags stay English kebab-case for clustering. Internal explanations from assistant should stay Korean (caveman-style is on, see below). +- **Hardware split:** Mac for company work, Windows for personal/side projects + Inkling dogfood. Has nvm available on Linux; Windows side will need nvm-windows or Volta. +- **Preferences:** + - Latest LTS Node + latest stable major libraries. Current pin: Node 24.15.0 (Krypton). Update spec §7.2 + `package.json` together if newer stable surfaces during install. + - Auto mode active in last session (execute autonomously, minimize interruptions). + - Caveman mode active in last session (drop articles/filler/pleasantries, fragments OK, technical substance preserved). Default level: full. Code/commits/security: write normal. + - Korean responses required regardless of caveman intensity. +- **Workflow expectations:** Comfortable with one-question-at-a-time brainstorming, design-then-plan-then-execute. Approves succinctly ("응" / "B" / "응 그리고 ..."). + +--- + +## Project state at handoff + +**Git:** initialized repo, branch `main`, 7 commits (no remote yet). No tags. + +``` +a5afdc5 docs(strategy): Inkling 심리학 기반 습관화 전략 문서 추가 ← user added +35f900b Rewrite implementation plan to v0.2 with Strategy integration +c7bfd15 Update vertical slice spec to v0.2 with Strategy integration +4b25ba3 Add vertical slice implementation plan ← v0.1 (superseded) +cdb329e Pin Node 24.15.0 LTS via .nvmrc +e22194b Add tech stack and version policy section to vertical slice spec +bbbe292 Add vertical slice design spec for Inkling MVP ← v0.1 (superseded) +``` + +**Files in repo:** +- `.nvmrc` (24.15.0) +- `inkling.md` (product brief) +- `docs/superpowers/strategy/strategy.md` (psychology strategy) +- `docs/superpowers/specs/2026-04-24-inkling-vertical-slice-design.md` (v0.2) +- `docs/superpowers/plans/2026-04-24-inkling-vertical-slice.md` (v0.2, 33 tasks) +- `docs/handoff/2026-04-25-linux-to-windows.md` (this file) + +**No code yet.** No `package.json`, no `src/`, no `tests/`, no `node_modules/`. + +--- + +## Implementation plan summary (33 tasks) + +**Bootstrap (Tasks 1–5):** project init, Electron entry + Inbox shell, typed preload, logger, paths. + +**Data layer (Tasks 6–9):** SQLite migration v1 (with `user_intent`, `intent_prompted_at`, `title_edited_by_user`, `summary_edited_by_user` columns), NoteRepository (with edited-flag overwrite guard), MediaStore, ContinuityService (Weekly Continuity, KST Mon-Sun, 7 notes/week, recovery detection). + +**AI layer (Tasks 10–13):** zod schema validator (Korean title required, kebab tag filter, summary normalization to 3 lines), prompt template, InferenceProvider interface, LocalOllamaProvider (120s timeout), AiWorker (3-attempt backoff: immediate / 30s / 120s). + +**Capture (Tasks 14–17):** CaptureService (with `enqueue` + `celebrate` hooks), NotificationService (4 rotating reward copies via SHA-256 mod 4), IPC captureApi, HotkeyService. + +**Quick Capture (Tasks 18–19):** frameless 640x280 popup, React UI with paste-image + ctrl-enter + esc. + +**Inbox (Tasks 20–28):** IntentService, IPC inboxApi, React shell + Zustand store + recoveryToast helper, ContinuityBadge, PendingBanner, NoteCard (AI labels + IntentBanner slot + intent badge), EditableField, IntentBanner (4 rotating prompts), RecoveryToast. + +**Wiring (Tasks 29–31):** HealthChecker + OllamaBanner, tray with v0.2 copy + main entry final wiring, MediaGc. + +**Verification (Tasks 32–33):** Playwright smoke + manual dogfood checklist (Strategy + base flows). + +Each task is bite-sized, follows red → green → commit. No batching. + +--- + +## Windows-specific gotchas to anticipate + +- **Node install:** `.nvmrc` says `24.15.0`. nvm-windows uses different syntax (`nvm install 24.15.0` then `nvm use 24.15.0`). Volta auto-detects `.nvmrc`. Either is fine — user's choice. +- **Native modules:** `better-sqlite3` requires a C++ build chain on first install. On Windows: `npm install --global windows-build-tools` is deprecated; the modern path is Visual Studio Build Tools 2022 with "Desktop development with C++" workload. If install fails, this is the first thing to check. +- **Ollama:** must be running with `gemma4:9b` pulled before AI tests work. `ollama serve` (background) + `ollama pull gemma4:9b`. Health check expects `http://localhost:11434/api/tags` to list `gemma4:9b`. +- **Global hotkey conflict:** `Ctrl+Shift+J` on Windows can collide with Chrome DevTools or Edge DevTools when those apps have focus. Pre-flight check: close DevTools-using apps before dogfood. +- **OS notification permission:** first `new Notification(...)` triggers a Windows toast permission flow. If denied, NotificationService falls back silently — capture still works. User can re-enable via Settings → Notifications → Inkling. +- **Code signing:** out of scope for this slice. `electron-vite` produces unsigned dev build. Windows Defender SmartScreen may warn on first launch — click "More info" → "Run anyway". +- **File paths:** `app.getPath('userData')` returns `%APPDATA%\Inkling\...` on Windows. Logs and DB end up there. Tests use `:memory:` SQLite + tmpdir for media — no Windows-specific issues expected. +- **Line endings:** `.gitattributes` not yet set. Recommend adding `* text=auto eol=lf` to prevent CRLF noise in tests. Optional for slice. +- **Playwright Electron E2E:** `_electron.launch({ args: [resolve('out/main/index.js')] })` works cross-platform. Build (`npm run build`) before E2E. + +--- + +## Memory hints for the new session + +The new Claude Code session on Windows will start with empty memory dir. Recommend writing these on day 1: + +- **user (file: `user_profile.md`):** Role + Korean preference + hardware split + LTS preference + caveman/auto-mode habits. Source: this handoff §"User profile". +- **feedback (file: `feedback_brainstorm_style.md`):** User responds to one-at-a-time multiple-choice questions tersely ("응" / letter pick). When confirming a non-obvious choice (like bumping weekly target from 3 to 7), note it as validated judgment, not casual approval. +- **feedback (file: `feedback_caveman_mode.md`):** Caveman mode (full) is on and is the user's default. Drop articles/filler/pleasantries. Code/commits/security write normal. Korean output required regardless. +- **project (file: `project_inkling_status.md`):** As of 2026-04-25, spec v0.2 + plan v0.2 are committed but no code. Slice = vertical slice MVP. Aha Moment is "7-day-3-consecutive-records" (KPI §7.1 of inkling.md) but slice itself measures via 2-week dogfood completion (spec §1.3). **Why:** verify whether plan execution should proceed or whether scope/tech decisions need refresh based on Windows reality. +- **reference (file: `reference_docs.md`):** Spec at `docs/superpowers/specs/2026-04-24-inkling-vertical-slice-design.md`, plan at `docs/superpowers/plans/2026-04-24-inkling-vertical-slice.md`, strategy at `docs/superpowers/strategy/strategy.md`, product brief at `inkling.md`. Always check these before recommending architecture changes. + +--- + +## Load-bearing invariants (do not relitigate) + +- **`raw_text` is immutable.** No update method exists. Don't add one. (Spec §3.3, principle 1) +- **AI re-runs do not overwrite user-edited title/summary.** Guard via `*_edited_by_user` columns + CASE WHEN in `updateAiResult`. (Spec §3.3, Plan Task 7) +- **IntentBanner appears exactly once per note.** Gate: `intent_prompted_at IS NULL`. Both setIntent and dismissIntent close the gate. (Spec §3.3, Plan Task 22+27) +- **Logs never contain `raw_text`/`ai_title`/`ai_summary`/`user_intent` content.** Only IDs, lengths, hash prefixes. (Spec §6.2, Plan Notes) +- **The words "실패", "끊김", "연속 실패" are forbidden in all UI strings in this slice.** Recovery-friendly tone enforced. (Spec §1.1, Plan Notes) +- **Native notifications must never block submit.** Permission denied = silent fallback. (Spec §6.1 row 10, Plan Task 15) +- **Versions are pinned exactly (no `^`).** Update spec §7.2 + `package.json` together if `npm install` reveals a newer stable major. (Spec §7.1, Plan Task 1) + +--- + +## Suggested first messages on Windows + +If the user wants to start fresh execution: + +> Read `docs/handoff/2026-04-25-linux-to-windows.md`, then the spec and plan it points to. Once oriented, ask whether to begin Task 1 of the plan (project bootstrap) or to do a quick Windows-environment sanity check first (Node version, build tools, Ollama running). + +If the user already started a `git status` and there are local changes (e.g. `node_modules` after a partial install): + +> Don't squash or destroy any work. Inspect first. The plan begins from a clean state with no dependencies installed. + +--- + +## What this session did NOT do + +- No code written +- No `npm install` run on Linux +- No tests run +- No Ollama model downloaded or benchmarked +- No remote git pushed (no GitHub URL exists) +- No CI configured + +The new session inherits a clean greenfield with one design and one plan. Execution is the next phase.