Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,25 @@ All notable changes to adhd-ranch. Follows [Keep a Changelog](https://keepachang

---

## [0.1.5] — 2026-10-17

### Added

- Save custom timer durations as reusable chips shared across Focus and Task timer pickers. Saved durations survive restart; removing a chip leaves running timers and the built-in 10/30/60-minute choices intact (PR #89).
- Install or repair the Claude Code hook plugin from Ranch through an explicit Install Hooks action. Agent visibility remains opt-in; toggling it off leaves the plugin installed (PRs #85–#86).

### Changed

- Rust now owns the flat Animal render scene and species profile, keeping Focus and Agent Session projections independent (PR #88).
- Document the current Ranch baseline, its existing automated proof, and the native acceptance checks still awaiting owner testing (`specs/003-ranch-today/`).

### Known limitations and testing

- Task Timers are bound to Task position; external insertion or reordering can move a timer to another Task.
- Late hook frames can still apply, missed session endings can leave stale observations, and older direct Claude hook entries are not removed automatically.
- Windows packages include the app but do not support hook delivery.
- Native UI, display, notifications, live Claude delivery, and packaged runtime network acceptance remain pending owner testing after release. Automated and package-build checks do not certify those scenarios.

## [0.1.4] — 2026-09-20

### Added
Expand Down
32 changes: 32 additions & 0 deletions specs/003-ranch-today/contracts/current-behavior.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Current UI and IPC Contracts

**Status**: Draft baseline evidence, 2026-10-17. This maps the clarified [spec](../spec.md) to existing interfaces, without introducing endpoints or wire formats. Constitution I–IV govern these boundaries even where implementation is incomplete.

## Boundary ownership

- **User → work:** card/tray actions use [Focus writer](../../../src/api/focusWriter.ts) and [Tauri bridge](../../../src-tauri/src/ui_bridge/mod.rs). Hand-edits enter through the watcher. Task operations address a Focus and current index; Timer operations use `TimerOwner`. Complete, Delete, and Clear are distinct.
- **Core → UI:** [Focus reader](../../../src/api/tauriFocusReader.ts), [scene reader](../../../src/api/tauriRenderSceneReader.ts), [Settings API](../../../src/api/settings.ts), and [Agent diagnostics](../../../src/api/agentDebug.ts) expose existing commands/events. Rust owns wire shapes and generated TypeScript; no duplicate schema is introduced.
- **Domains → renderer:** [RenderScene](../../../crates/commands/src/render_scene.rs) is flat. [App selection](../../../src/components/App.tsx) resolves Focus details separately. Agent Animals have no Focus editing, Timer ownership, or Limit contribution.
- **Claude → Ranch:** explicit plugin install uses the local CLI at user scope. A stable client delivers bounded Unix-socket frames; Windows has no delivery. Plugin health is separate from observed delivery. [Research](../research.md) distinguishes current shortcomings from accepted ADR direction.
- **Network:** no Ranch HTTP/network API. Vite development traffic and effects of explicit local Claude CLI actions must not be misreported as Ranch product network features.

## Observable contract and coverage

V1–V7 refer to [quickstart](../quickstart.md). FR-013–FR-015 require accurate observations, not tests requiring bugs to remain.

| Spec entries | Observable contract | Existing proof owner / validation |
|---|---|---|
| FR-001, FR-002 | Canonical local files; explicit edits; Complete retains, Delete removes, Clear affects only Timer; malformed sidecars do not block Focus. | [Store](../../../crates/storage/src/focus_store.rs), [workflows](../../../crates/commands/src/focus.rs); V1/V2. |
| FR-003 | One Timer owner; built-ins 10/30/60 and shared saved custom chips; chip removal leaves running Timer; add Task revives only Expired Focus. | [Timers](../../../crates/commands/src/timers.rs), [Settings workflow](../../../src-tauri/src/app/settings_workflow.rs); V1. |
| FR-004, FR-005, FR-009 | One Pig per Focus; enabled displays/no gaps; drag/toss/Gather; empty-space click-through; Focus-only card closes outside/Escape. | [Scene contract](../../../crates/commands/tests/render_scene_contract.rs), [App tests](../../../src/components/App.test.tsx), [movement tests](../../../src/lib/animalMovement.test.ts); V3. |
| FR-006, FR-007, FR-008 | Tray actions, delete confirmation, red Over Limit; soft defaults 5/7; editable Settings apply immediately; writes allowed; Agents excluded. | [Tray](../../../src-tauri/src/app/tray.rs), [Limits](../../../crates/commands/src/caps.rs), [Settings workflow](../../../src-tauri/src/app/settings_workflow.rs); V4/V5. |
| FR-010, FR-011 | Agents default off; non-editable observed sessions; toggle leaves plugin; explicit install/repair; diagnostics include unchanged Firings. | [Plugin](../../../src-tauri/src/app/claude_plugin.rs), [socket tests](../../../crates/storage/tests/agent_hook_socket.rs), [journal](../../../crates/storage/src/agent_hooks/journal.rs); V5. |
| FR-012, FR-017 | Ambient operation, allowed notifications/user-opened windows only; no outbound product network/model/telemetry; IPC boundary. | Constitution, source review, native/network observation V3/V6. |
| FR-013 | Positional Timer drift is an observation, not a preservation requirement. | [Storage mapping](../../../crates/storage/src/focus_store.rs), draft [004](../../004-task-timer-hand-edits/spec.md); V7. |
| FR-014 | Late-frame eligibility, indistinguishable stop endings, and invalidation/refetch recorded alongside ADR-0002 drift. | [Server](../../../crates/storage/src/agent_hooks/server/unix.rs), [events](../../../src-tauri/src/app/agent_hooks.rs), [reader](../../../src/api/tauriAgentSessionReader.ts); V7. |
| FR-015 | Legacy direct entries remain; new install uses plugin/stable client. No cleanup added. | [Client placement](../../../src-tauri/src/app/claude_hook.rs), draft [007](../../007-one-hook-delivery/spec.md); V7. |
| FR-016 | macOS primary; Windows package builds passed; Linux packaging is an FR-016 target with build evidence still unverified; no Windows hook delivery. | [Windows workflow](../../../.github/workflows/windows.yml), [release matrix](../../../.github/workflows/release.yml); platform gates. |
| FR-018, FR-019, FR-020 | No sync/multi-user/import service, external work writer, auto-complete/merge, network API, slash command, or Harness notification forwarding. | Scoped source review V6; fixture file diffs V1/V5 check absence of unsolicited writes in exercised scenarios. |
| FR-021, FR-022 | Primary-only default; Gather/no Wrangle; Pig and Claude Code only. | [Settings](../../../crates/domain/src/settings.rs), [Species](../../../crates/commands/src/render_scene.rs), tray; V3/V4/V6. |

SC-001 → V3; SC-002 → V1; SC-003 → V2; SC-004 → V4/V5; SC-005 → V5; SC-006 → V6. Source inspection and old tests must not substitute for fresh native results.
43 changes: 43 additions & 0 deletions specs/003-ranch-today/data-model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Data Model: Ranch Today

**Status**: Draft description of current implementation, checked 2026-10-17. No new schema, stable Task identity, database, or migration.

## User-owned work

| Entity | Current fields / relationship | Validation and persistence |
|---|---|---|
| Focus | `id: FocusId(String)`, `title`, `description`, `created_at`, ordered `tasks`, optional `timer` | [Domain](../../crates/domain/src/focus.rs), [parser](../../crates/domain/src/parse.rs), [storage](../../crates/storage/src/focus_store.rs). Metadata and checkbox Tasks in `focus.md`; parser requires frontmatter with `id` and `title`. |
| Task | `id`, `text`, `done`, optional `timer`; belongs to one Focus | App writes reject blank text. Parser derives ID as `focus_id:index` from nonempty checkbox lines; no stable persisted Task ID. Complete checks the retained line; Delete removes it. |
| Timer | `duration_secs`, `started_at` (epoch seconds), `status: Running / Expired` | [Timer domain](../../crates/domain/src/timer.rs), [workflow](../../crates/commands/src/timers.rs). Focus Timer in `timer.json`; indexed Task Timers in `task-timers.json`. Missing/corrupt optional sidecars load as no Timer. |
| TimerOwner | Tagged `Focus { focus_id }` or `Task { focus_id, index }` | Selects one owner for start/restart/Clear. Positional addressing is an observation, not protection against hand-edit drift (FR-013). |
| Settings | `caps`, `notifications`, `widget`, `displays`, `agents`, `pens`, `timers` | [Types/defaults](../../crates/domain/src/settings.rs), [host workflow](../../src-tauri/src/app/settings_workflow.rs), `settings.yaml`. Saved custom minutes are positive, unique, and exclude built-ins 10/30/60. Frontend timer presets define the current picker; legacy backend preset variants do not define its menu. |
| Limit state | Focus count, over-Focus flag, IDs of Focuses above Task threshold | [Evaluator](../../crates/domain/src/caps.rs) reads Focuses, not Agent Sessions. Defaults 5/7. Completed Tasks count because all stored Tasks are counted; writes above a threshold remain permitted. |

The data root is `ADHD_RANCH_HOME` when set, otherwise `~/.adhd-ranch` on Unix, with platform path fallbacks on Windows. [Path resolution](../../src-tauri/src/app/paths.rs) is authoritative. No archive layout from draft spec 008 is adopted.

## Observed activity

| Entity | Current fields | Ownership / lifecycle |
|---|---|---|
| Agent Session | `id`, `name`, `pen`, `activity: Working / Idle` | [Model](../../crates/domain/src/session/agent_session.rs), [live store](../../crates/storage/src/agent_session_store.rs). Observed from Claude hooks, in memory, never a Focus or Timer owner. |
| Pen | `id`, `name`, derived from repository checkout path | [Pen domain](../../crates/domain/src/session/pen.rs). Groups Agent Sessions, not user work. |
| Hook Firing | `at`, `action: Start / Working / Idle / End`, optional `session_id`, optional `pen`, `changed` | [Types](../../crates/domain/src/agents/hooks.rs), [journal](../../crates/storage/src/agent_hooks/journal.rs). Recent diagnostics retain unchanged Firings; no transcript archive. |
| Hook Wiring | `agent`, `settings_file`, `client_bin`, `socket_path`, `installed`, `enabled` | Same hook types. Validated configuration is distinct from observed delivery. |

Current hooks fold arrival order; Stop and StopFailure map to Idle. No source stamp or transport-change entity exists in today's exported model. This differs from ADR-0002's accepted target; see [research](research.md#5-record-accepted-decision-drift-without-enshrining-it).

## Shared render projection

[RenderScene](../../crates/commands/src/render_scene.rs) contains `animals`, `regions`, and `speciesProfiles`. Each Animal has `id`, `label`, `species`, `size`, optional `regionId`, and `motion`. Species is Pig; Motion is Walking or Resting. Size is fixed or linearly sampled over time. Region rectangles describe enabled display layout; [DisplaySpace](../../src/types/display.ts) supplies frontend geometry.

Each domain projects its state into this flat vocabulary. Movement and sprites consume neither domain types nor source discriminators. Selection resolves separately to a Focus; it cannot make an Agent Animal editable. Rust and [the wire contract test](../../crates/commands/tests/render_scene_contract.rs) own the shape; `src/types/generated/` stays generated.

## State transitions

- **Task:** add → unchecked; Complete → checked in place; undo → unchecked; Delete → removed. Editing text preserves completion. None is Timer Clear.
- **Timer:** start/restart → Running with fresh start time; due Running → Expired with timer-only persistence; Clear → absent. Adding a Task clears an Expired Focus Timer (Revive), never a Task Timer.
- **Focus projection:** running Focus Timer drives growth; Expired drives resting/ghostly/away appearance and tray Expired membership. Task Timer expiry changes neither projection nor tray membership.
- **Limits:** crossing above a threshold produces one transition and an allowed notification, not repeated notifications while above. Agent activity cannot change it.
- **Agent:** Start establishes a session; Working/Idle update activity; End removes it. Disabling Agents hides/clears observed sessions and leaves the plugin installed. No activity state uses Focus Timer expiry.

These relationships preserve Constitution I–IV without authorizing new writes or installation.
100 changes: 100 additions & 0 deletions specs/003-ranch-today/plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# Implementation Plan: Ranch Today Baseline Validation

**Feature context**: `003-ranch-today` | **Date**: 2026-10-17 | **Spec**: [spec.md](spec.md)

**Checkout branch**: `main` at `a48525d9a89555bf9bc925a20d626c0dc634b4ce`

**Status**: Draft. The specification remains Draft; these artifacts support owner review and do not promote it to approved authority.

**Input**: `specs/003-ranch-today/spec.md`, including the 2026-10-17 clarification that known limitations are observations which follow-on specifications may fix.

## Summary

Establish a reviewable baseline for the existing local-first desktop product: Focus and Task editing, Timers, ambient Animals, tray and Settings, hand-edited Markdown, and optional Claude Code observations. Reuse existing code and tests, document current contracts, and prepare a repeatable validation pass. No runtime implementation, dependencies, storage migration, new IPC, or archive work is proposed.

FR-013–FR-015 are observations, not behavior to preserve. ADR-0002's accepted transport direction is not fully implemented in current code; [research](research.md) records that discrepancy without approving it or absorbing its follow-on work into 003.

## Technical Context

**Language/Version**: Rust edition 2021, declared minimum 1.77; TypeScript ^5.6.3. Existing manifests and lockfiles govern installed versions.

**Primary Dependencies**: Tauri v2 (^2.1 API/CLI declarations), React ^18.3.1, Vite ^5.4.11, serde/serde_json, ts-rs-generated frontend types. No dependency changes.

**Storage**: Focus directories with `focus.md`, optional `timer.json` and `task-timers.json`; `settings.yaml` under the Ranch data root. Agent Sessions and recent Hook Firings are runtime observations, not user work. See [data model](data-model.md).

**Testing**: Existing Rust unit/integration tests, Vitest ^2.1.8, generated-type drift checks, native manual scenarios. [Quickstart](quickstart.md) distinguishes available coverage from checks actually executed.

**Target Platform**: macOS primary; retain Windows and Linux package compatibility. Windows has no hook delivery. No platform code changes.

**Project Type**: Tauri desktop application with Rust workspace and React webviews; Tauri IPC is the frontend/core boundary.

**Performance Goals**: Hand-edited Markdown visible within about one second (SC-003); ambient rendering without unsolicited attention. No new FPS or throughput target.

**Constraints**: User-controlled atomic local writes; safe malformed optional sidecars; independent Focus and Agent Session domains; no outbound product network, telemetry, model calls, or stored provider credentials. Integration install remains explicit.

**Scale/Scope**: One local user; one Animal per Focus plus optionally observed Claude Code sessions. Soft defaults 5 Focuses / 7 Tasks per Focus are thresholds, not capacity ceilings. Five user stories, 22 FR entries including three observations, six success criteria.

## Constitution Check

These gates apply to this documentation and validation design, not a certification of all existing runtime behavior.

| Principle / gate | Before research | After design |
|---|---|---|
| I — User-owned local state | PASS: inspect existing files; no migration or personal-data writes. | PASS: synthetic validation data; no new write path or network service. |
| II — Independent domains | PASS: preserve the accepted renderer seam. | PASS: Agent activity remains separate from Focus Timers, editing, and Limits. |
| III — Functional core, typed edges | PASS: reuse existing layers and generated contracts. | PASS: source owners linked; no code or generated-type edits. |
| IV — Explicit integrations | PASS: no installation during planning. | PASS: isolated delivery proof; optional live check; configuration health is not delivery. |
| V — Observable small slices | PASS: baseline evidence only. | PASS: four bounded validation slices below; no passing-test or shipped-completion claim. |
| VI — Evidence and authority | PASS: keep the spec Draft and classify sources. | PASS: distinguish accepted ADR direction, observed code, and draft follow-ons; document existing transport drift. |

**Gate result:** PASS for Phase 0 and Phase 1 planning. No new exception is requested. ADR-0002 drift is an existing gap, not a compliant runtime result. Follow-on work must reconcile lower-level artifacts with accepted decisions before implementation. Owner approval of the current specification remains necessary before treating it as governing an implementation.

## Project Structure

### Documentation (this feature)

```text
specs/003-ranch-today/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
└── current-behavior.md
```

`tasks.md` is a later `$speckit-tasks` output, not created by this command.

### Existing source and proof locations (repository root)

```text
crates/domain/src/ # Pure Focus, Task, Timer, Settings, session and hook types
crates/storage/src/ # Files, watcher, hook transport and journal
crates/storage/tests/ # Socket/client and storage fixtures
crates/commands/src/ # Workflows, Limits and render projections
crates/commands/tests/ # Render wire contract
crates/hook-client/src/ # Bounded local hook client
src-tauri/src/app/ # Composition, tray, windows, settings and plugin adapters
src-tauri/src/ui_bridge/ # Tauri commands and events
src/api/ # Typed IPC readers and writers
src/hooks/ # UI state and frame mechanics
src/components/ # Views and interaction tests
src/lib/ # Movement, display and timer-picker helpers
src/types/generated/ # Generated contracts, never manually edited
```

**Structure Decision**: Keep the existing layout. This phase authors only five planning documents. Application code, unrelated dirty files, and the clarified specification remain unchanged.

## Validation Slices

1. **Files and Timers:** verify Task edits, Timer ownership/expiry/revival, optional sidecar failures, and persistence using existing tests plus card/file observations. Promise: accurately describe user work without making positional drift a rule.
2. **Ambient shell:** verify selection, movement, displays, Gather, tray, Settings, and soft Limits. Promise: visible behavior and platform-dependent gaps have explicit evidence or an unverified result.
3. **Agent boundary:** verify opt-in visibility, non-editability, exclusion from Limits, plugin health, unchanged Firings, and isolated delivery. Promise: configuration and actual delivery are reported separately.
4. **Evidence reconciliation:** map all FRs/SCs through [the contract](contracts/current-behavior.md) and [quickstart](quickstart.md), record commands/results/platform/commit, and route discrepancies to their owning follow-on. Promise: no acceptance claim rests only on source inspection or old CI.

A discovered mismatch is evidence to report, not authorization for unrelated fixes. New acceptance gaps need a narrow issue. FR-013–FR-015 already have follow-on context. Any later runtime slice requires relevant gates after synchronization with current main, independent review, green CI, and merge before shipping completion is claimed.

## Complexity Tracking

No new abstraction, protocol, schema, dependency, or constitutional exception. Existing accepted-decision drift is recorded in [research](research.md#5-record-accepted-decision-drift-without-enshrining-it).
Loading
Loading