From 24af070120edc7f3528b9b57e3b5509cb8380268 Mon Sep 17 00:00:00 2001 From: archae0pteryx Date: Sat, 17 Oct 2026 15:01:19 -0700 Subject: [PATCH 1/2] [ranch-baseline]: Record current behavior and release evidence --- CHANGELOG.md | 19 ++ .../contracts/current-behavior.md | 32 +++ specs/003-ranch-today/data-model.md | 43 ++++ specs/003-ranch-today/plan.md | 100 +++++++++ specs/003-ranch-today/quickstart.md | 89 ++++++++ specs/003-ranch-today/research.md | 58 +++++ specs/003-ranch-today/spec.md | 43 +++- specs/003-ranch-today/tasks.md | 204 +++++++++++++++++ .../003-ranch-today/validation/pass-record.md | 209 ++++++++++++++++++ specs/003-ranch-today/validation/us1.md | 21 ++ specs/003-ranch-today/validation/us2.md | 18 ++ specs/003-ranch-today/validation/us3.md | 17 ++ specs/003-ranch-today/validation/us4.md | 16 ++ specs/003-ranch-today/validation/us5.md | 19 ++ 14 files changed, 879 insertions(+), 9 deletions(-) create mode 100644 specs/003-ranch-today/contracts/current-behavior.md create mode 100644 specs/003-ranch-today/data-model.md create mode 100644 specs/003-ranch-today/plan.md create mode 100644 specs/003-ranch-today/quickstart.md create mode 100644 specs/003-ranch-today/research.md create mode 100644 specs/003-ranch-today/tasks.md create mode 100644 specs/003-ranch-today/validation/pass-record.md create mode 100644 specs/003-ranch-today/validation/us1.md create mode 100644 specs/003-ranch-today/validation/us2.md create mode 100644 specs/003-ranch-today/validation/us3.md create mode 100644 specs/003-ranch-today/validation/us4.md create mode 100644 specs/003-ranch-today/validation/us5.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c960df2..f445cc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/specs/003-ranch-today/contracts/current-behavior.md b/specs/003-ranch-today/contracts/current-behavior.md new file mode 100644 index 0000000..ad945c1 --- /dev/null +++ b/specs/003-ranch-today/contracts/current-behavior.md @@ -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; Linux/Windows packages build; 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. diff --git a/specs/003-ranch-today/data-model.md b/specs/003-ranch-today/data-model.md new file mode 100644 index 0000000..85461b5 --- /dev/null +++ b/specs/003-ranch-today/data-model.md @@ -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. diff --git a/specs/003-ranch-today/plan.md b/specs/003-ranch-today/plan.md new file mode 100644 index 0000000..6b7781c --- /dev/null +++ b/specs/003-ranch-today/plan.md @@ -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). diff --git a/specs/003-ranch-today/quickstart.md b/specs/003-ranch-today/quickstart.md new file mode 100644 index 0000000..786a471 --- /dev/null +++ b/specs/003-ranch-today/quickstart.md @@ -0,0 +1,89 @@ +# Validation Guide: Ranch Today + +**Status**: Draft guide, not an execution report. Planning inspected source and test definitions only. See [contract coverage](contracts/current-behavior.md) and [data model](data-model.md). + +## Prerequisites and isolation + +Use the [development setup](../../README.md), repository toolchains, Node, Task, and RTK. macOS is the native design target. Run from the repository root. Before final implementation validation, synchronize the validation branch with current main and record its commit; preserve unrelated changes. + +Use synthetic data in a fresh short temporary path to fit Unix socket path limits. Quit other Ranch instances first. Do not copy personal Focuses, Claude settings, credentials, or transcripts. + +```sh +rtk mktemp -d /tmp/ranch003.XXXXXX +``` + +Replace `/tmp/ranch003.ABC123` below with the directory printed above. Give Ranch a separate data root and empty Claude configuration: + +```sh +rtk mkdir -p /tmp/ranch003.ABC123/ranch /tmp/ranch003.ABC123/claude +rtk env ADHD_RANCH_HOME=/tmp/ranch003.ABC123/ranch CLAUDE_CONFIG_DIR=/tmp/ranch003.ABC123/claude task dev +``` + +Do not choose Install Hooks during basic smoke checks. A separate Claude process needs the same environment values for the optional live check. + +## Existing automated gates + +```sh +rtk task test:rust +rtk task test:web +``` + +Existing proof targets: + +| Area | Tests already in the repository | +|---|---| +| Markdown edits, sidecars, positional mapping | [Focus store](../../crates/storage/src/focus_store.rs) | +| Timer start/Clear/expiry/revival and projection | [Timers](../../crates/commands/src/timers.rs), [Focus Animals](../../crates/commands/src/focus_animals.rs) | +| Scene shape, mixed selection, movement, Escape | [Render contract](../../crates/commands/tests/render_scene_contract.rs), [App](../../src/components/App.test.tsx), [movement](../../src/lib/animalMovement.test.ts), [detail](../../src/components/AnimalDetail.test.tsx) | +| Chips, concurrent saves, Limits crossings | [Settings workflow](../../src-tauri/src/app/settings_workflow.rs), [Limits](../../crates/commands/src/caps.rs) | +| Plugin health/repair, client, unchanged Firings, delivery/absent-app success | [Plugin](../../src-tauri/src/app/claude_plugin.rs), [client](../../src-tauri/src/app/claude_hook.rs), [journal](../../crates/storage/src/agent_hooks/journal.rs), [socket integration](../../crates/storage/tests/agent_hook_socket.rs) | + +A later shipping slice must pass `rtk task check`: lint, typecheck, tests, generated-type drift. Platform changes also need relevant gates: `rtk task check:windows` checks cross-target compilation; real Windows bundling uses [Windows CI](../../.github/workflows/windows.yml), Linux packaging the [release matrix](../../.github/workflows/release.yml). Compilation is not native behavioral proof. Planning does not run release workflows or add tests for prose. + +## Native scenarios + +For each scenario record pass/fail/unverified, platform, commit, and evidence. On first fixture launch expect one example Focus. Delete it and restart: its marker prevents reappearance. Create two clearly named Focuses for further checks. + +### V1 — Files, card, and Timers + +Rename and duplicate a Focus; compare files and Animals. Add/edit two Tasks, Complete/undo one, then Delete it. Inspect fixture `focuses//focus.md`: Complete checks a retained line, Delete removes it. Blank Task input must not create a Task. + +Start/restart/Clear Focus and Task Timers and inspect their owning sidecars; Clear retains work. Check built-ins 10/30/60 and shared custom chips across pickers/restart. Remove saved chips during a running Timer: Timer and built-ins remain. + +Use short custom Timers to observe Focus growth then expiry (ghostly/resting/away, tray Expired). Adding a Task revives that Focus. Task Timer expiry changes its status/allowed notification without changing Animal size/motion or tray Expired membership; adding a Task never revives another Task's Timer. In disposable fixture copies, missing/corrupt optional sidecars must still permit loading the Focus. Existing tests cover atomic-write failure cases. + +### V2 — Hand edits and durability + +Append a nonempty checkbox in fixture Markdown; time save-to-card visibility. Complete a checkbox externally and repeat. Record actual elapsed time against SC-003's approximately one-second outcome; debounce is not a measurement. Restart and verify work, Timers, and saved Settings survive. Hand-edited Settings apply on restart, not by live Settings-file watching. + +### V3 — Ambient overlay and displays + +Name the open Focuses from visible labels. Confirm one Pig per Focus, drag/toss, and Gather to primary. Click empty overlay space: the underlying app receives it. Close a Focus card by outside click/Escape. Work in another app: Ranch must not raise a window or take attention on its own. + +Verify primary-only defaults; with multiple displays, enable another and check movement stays in visible regions rather than gaps. Mark that portion unverified without appropriate hardware. Native click-through, attention, visual usefulness, and ghosting need observations beyond component tests. + +### V4 — Tray, Settings, and soft Limits + +Check New Focus, cancel/confirm delete, Gather, Agents toggle, Settings, and quit. Cancellation preserves the Focus. Verify default Limits 5/7, then lower them for a short crossing test. Writes above either threshold still save, tray turns red, and an enabled notification fires once per crossing rather than repeatedly. Completed Tasks still count. Repeat with notifications disabled: no notification fires. App Settings apply immediately and persist after restart. + +### V5 — Agent independence and delivery + +Run isolated plugin/socket/journal tests first; these are not a census of live sessions. Fresh UI defaults to Agents off. Enabling alone must not install a plugin; opening an Install Hooks dialog is distinct from executing installation. + +An optional live check requires a disposable Claude configuration that can run independently. Do not borrow credentials from the normal environment. Launch Claude with the same `ADHD_RANCH_HOME` and `CLAUDE_CONFIG_DIR` as Ranch, then explicitly choose Install Hooks. Record configuration health separately from an observed Firing, including an unchanged repeat. The session must emit a hook after Ranch starts listening; there is no cold-start census. Mark live delivery unverified if the isolated environment cannot run. + +With an observed session, show its Animal, click it (no Focus card), and confirm activity neither changes work files nor contributes to Limits. Toggle visibility off: Focus Animals and installed plugin remain. Compare fixture files before/after activity. Do not read personal transcripts. Windows hook delivery is unsupported. + +### V6 — Runtime boundaries and non-goals + +Review writers, exposed commands, and dependencies for the exclusions in the contract map: no sync/import service, external work writer, auto-completion/merging, Harness notification forwarding, Wrangle, second Species/Harness, outbound client, telemetry, model call, or stored provider credential. This is scoped source evidence, not universal runtime proof. + +Observe a packaged Ranch process using platform process-scoped network inspection during core scenarios. Record tool, process, time window, and exercised actions: expect no outbound product connection or network API. Vite development traffic does not establish SC-006. Report explicit local Claude CLI actions separately. Mark runtime verification unverified without a packaged build or suitable observation tool. + +### V7 — Known limitations + +Record FR-013 positional drift, FR-014 transport/event gaps, and FR-015 retained legacy entries as source/fixture observations. Do not require reproducing them in personal data or fail future work because an approved feature fixes them. Explicitly report ADR-0002/current-code drift; [research](research.md) links follow-ons. No fixes are included in this baseline pass. + +## Completion evidence + +Record commit, platform, commands/exit statuses, native observations, unverified checks, and linked discrepancies in later task/issue evidence. Map all six SCs using the contract. Source inspection and past CI are not fresh success. Stop after baseline evidence is reconciled; runtime changes require separately approved scope, gates, review, and merge. diff --git a/specs/003-ranch-today/research.md b/specs/003-ranch-today/research.md new file mode 100644 index 0000000..d7b63c2 --- /dev/null +++ b/specs/003-ranch-today/research.md @@ -0,0 +1,58 @@ +# Research: Ranch Today + +**Date**: 2026-10-17 | **Status**: Draft planning evidence + +Research target: the clarified [specification](spec.md), checked against local `main` at `a48525d9a89555bf9bc925a20d626c0dc634b4ce`. Source inspection and a read-only research agent informed this record; tests and native smoke checks were not executed during planning. + +## Source inventory and authority + +| Classification | Source | Use in this plan | +|---|---|---| +| Governing rules | [Constitution](../../.specify/memory/constitution.md) | Local ownership, independent domains, typed boundaries, explicit integration lifecycle, and evidence requirements. | +| Accepted decisions | [ADR-0001](../../docs/adr/0001-two-apps-over-one-renderer.md), [ADR-0002](../../docs/adr/0002-agent-hook-transport.md), [ADR-0003](../../docs/adr/0003-rust-owned-render-scene.md) | Separate domains and a Rust-owned flat render scene; accepted hook direction is distinguished from current implementation below. | +| Present user direction | [Clarifications](spec.md#clarifications), 2026-10-17 | FR-013–FR-015 describe observations that follow-on work may fix. The planning request authorizes these draft artifacts; it does not silently change the specification's lifecycle status. | +| Verified source observations | [Workspace](../../Cargo.toml), [frontend manifest](../../package.json), [architecture](../../docs/architecture.md), source and test files linked below | Existing stack, storage, boundaries, and available proof. Test definitions establish coverage intent, not fresh passing results. | +| Settled vocabulary | [CONTEXT.md](../../CONTEXT.md) | Focus, Task, Timer, Animal, Agent Session, Limit, Complete, Delete, and Clear. | +| Non-normative context | [002](../002-speckit-docs-pass/spec.md), [004](../004-task-timer-hand-edits/spec.md), [005](../005-late-hook-frame/spec.md), [006](../006-unheard-turn-ends/spec.md), [007](../007-one-hook-delivery/spec.md), [008](../008-claude-session-storage/spec.md) | Documentation history and separate draft features. None supplies additional requirements for 003. Removed PRD content and icebox proposals are not design authority. | + +## Decisions + +### 1. Validate the existing product rather than rebuild it + +- **Decision:** Plan a baseline evidence pass for the five existing user stories, with no runtime changes or new dependencies. +- **Rationale:** The spec describes shipped behavior. [Focus workflows](../../crates/commands/src/focus.rs), [Timers](../../crates/commands/src/timers.rs), [scene projection](../../crates/commands/src/render_scene.rs), and [host composition](../../src-tauri/src/app/mod.rs) already implement the corresponding paths. +- **Alternatives considered:** A second implementation or folding all follow-on specs into this plan would duplicate working behavior and expand scope beyond the owner's clarification. + +### 2. Keep the current file model and generated contracts + +- **Decision:** Describe the existing Markdown, timer sidecars, Settings, and Rust-to-TypeScript contracts; introduce no schema or migration. +- **Rationale:** [Focus storage](../../crates/storage/src/focus_store.rs) owns `focus.md`, `timer.json`, and `task-timers.json`. [Parsing](../../crates/domain/src/parse.rs) derives Task IDs from Focus ID and checkbox position. [Paths](../../src-tauri/src/app/paths.rs) resolves the Ranch data root. These are current observations, not a reason to preserve positional drift. +- **Alternatives considered:** Stable Task IDs, a database, and a data-root rename belong to separately approved features. Generated TypeScript is not hand-edited documentation. + +### 3. Preserve domain ownership at the render boundary + +- **Decision:** Validate Focus and Agent Session projections independently, then their composition into `RenderScene`. +- **Rationale:** ADR-0003 refines ADR-0001 by assigning projection and layout to Rust. [Focus projection](../../crates/commands/src/focus_animals.rs), [Agent projection](../../crates/commands/src/agent_animals.rs), and [the scene contract test](../../crates/commands/tests/render_scene_contract.rs) make the seam observable. The movement and sprite layers consume renderer vocabulary. +- **Alternatives considered:** Adding domain flags or Timer/Hook logic to movement would violate the accepted boundary and is unnecessary for validation. + +### 4. Treat hook installation and delivery as separate evidence + +- **Decision:** Reuse isolated plugin, journal, and socket tests; reserve a real Claude run for a deliberately isolated manual check. +- **Rationale:** [Plugin validation/install](../../src-tauri/src/app/claude_plugin.rs) and [stable client placement](../../src-tauri/src/app/claude_hook.rs) cover configuration. [Socket tests](../../crates/storage/tests/agent_hook_socket.rs) cover delivery, including absent-app success. [Journal tests](../../crates/storage/src/agent_hooks/journal.rs) retain unchanged Firings. Configuration health alone does not prove that a live session delivered anything. +- **Alternatives considered:** Automatically installing into the developer's normal Claude configuration or reading personal transcripts is unnecessary. Cold-start census and transcript ingestion are outside this baseline. + +### 5. Record accepted-decision drift without enshrining it + +- **Decision:** Explicitly record the ADR-0002 implementation gap; do not implement or assert preservation of FR-013–FR-015 in this baseline. +- **Rationale:** ADR-0002's accepted decision calls for stamped frames, stale-frame rejection, and change-carrying events, and its checklist reports the first slice complete. Current [socket parsing](../../crates/storage/src/agent_hooks/server/unix.rs) still accepts `verb` plus payload, [session storage](../../crates/storage/src/agent_session_store.rs) folds arrival order, and [host events](../../src-tauri/src/app/agent_hooks.rs) emit unit invalidations. [The frontend reader](../../src/api/tauriAgentSessionReader.ts) refetches the list. The accepted direction therefore cannot be reported as fully shipped. [059](../../issues/059-self-describing-hook-frame.md) and [061](../../issues/061-hook-change-events.md) describe the transport/event follow-ons; [060](../../issues/060-session-staleness-sweep.md) describes missed-event recovery. These issue proposals are context, not additional authority or implementation instructions here. +- **Alternatives considered:** Claiming the ADR is fully implemented would be false. Reproducing bugs as permanent acceptance tests would contradict the user's answer. Silently changing the accepted ADR would conceal the discrepancy. + +### 6. Use existing gates and distinguish manual gaps + +- **Decision:** Use [Taskfile](../../Taskfile.yaml) gates and existing tests, then record manual observations for native behavior. +- **Rationale:** Existing tests cover core rules, persistence, render serialization, settings concurrency, plugin validation, and socket delivery. They do not establish OS click-through, attention behavior, visual usefulness, tray color, display gaps, actual notifications, or full watcher-to-UI latency. The watcher's debounce is not proof of SC-003's approximately one-second outcome. +- **Alternatives considered:** New tests solely for these planning documents would mirror prose. A dev-server connection is also not evidence of a product network API: Vite is development infrastructure. SC-006 needs a packaged-app observation, separately scoped from an explicit local Claude CLI action. + +## Resolution + +No unresolved technical choices remain for this documentation and validation scope. Runtime verification remains work to execute, not evidence already obtained. The current stack is retained at its repository-declared versions; no new library or external API research is needed. diff --git a/specs/003-ranch-today/spec.md b/specs/003-ranch-today/spec.md index 8521984..74743f8 100644 --- a/specs/003-ranch-today/spec.md +++ b/specs/003-ranch-today/spec.md @@ -8,6 +8,27 @@ **Input**: This specification converts the product requirements document into the current description of what the ranch does today. It stays Draft until the owner approves it. +## Clarifications + +### Session 2026-10-17 + +- Q: Should known bugs and limitations in Ranch Today be observations that later features may fix, or required behavior that future changes must preserve? → A: Record known limitations as observations of the current product; follow-on specifications may fix them. + +## Constitution Compliance Check + +This check applies to the scope and requirements of this Draft baseline; it does not certify that every current runtime path conforms. + +| Principle | Scope check | +|---|---| +| I — User-owned local state | FR-001–FR-003 preserve canonical local files, explicit user edits, safe optional sidecars, and timer-only expiry writes; FR-012 excludes outbound product network, telemetry, and model calls. | +| II — Independent domains | FR-005, FR-007, and FR-010 keep Agent Sessions separate from Focus editing, Timers, and Limits; domains meet through the accepted flat Animal render contract. | +| III — Functional core, typed edges | The baseline retains the existing pure domain rules, I/O adapters, Tauri IPC, and generated Rust-to-TypeScript contracts without proposing implementation changes. | +| IV — Explicit integrations | FR-010–FR-011 require opt-in visibility and explicit installation/repair; configuration health and observed delivery are separate evidence. | +| V — Observable completion | The plan and tasks validate existing behavior through current automated gates and native observations; failed or unverified criteria cannot support a completion claim. | +| VI — Evidence and authority | This spec remains Draft. Source observations and known limitations do not override the constitution or Accepted ADRs; Draft follow-ons are context, not additional requirements. | + +ADR-0002's accepted transport direction is not fully implemented today. FR-014 records that gap, not an approved alternative or exception; follow-on work must reconcile lower-level artifacts with accepted decisions before implementation. + ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Glance and know what is open (Priority: P1) @@ -71,17 +92,19 @@ The person edits a Focus file in their own editor. The overlay catches up within **Acceptance Scenarios**: 1. **Given** a Focus file, **When** the person adds or Completes a checkbox line and saves, **Then** the Animal's Task list matches the file. -2. **Given** a Task Timer sidecar stores Timers by Task position, **When** the person reorders or inserts Tasks by hand, **Then** a Timer can sit on a different Task than the one it was attached to. +**Current limitation:** Task Timers are stored by Task position, so a hand-edit that reorders or inserts Tasks can move a Timer onto another Task. This records current behavior; a follow-on specification may fix it. --- ### User Story 5 - See an agent without tracking it as work (Priority: P3) -The person can turn on Agents as Animals. Each running Claude Code Agent Session appears as an Animal. Those Animals are not Focuses: the person did not create them, they are not editable, they do not count toward Limits, and they disappear from the screen when the setting is turned off. The Claude plugin stays installed. +The person can turn on Agents as Animals. While enabled, each ongoing Claude Code Agent Session the ranch has observed through Hook Firings appears as an Animal. Those Animals are not Focuses: the person did not create them, they are not editable, they do not count toward Limits, and they disappear from the screen when the setting is turned off. The Claude plugin stays installed. + +**Current limitation:** A session already running when the ranch starts listening stays unseen until it sends a Hook Firing. The ranch does not enumerate running sessions at startup. This is an observation that a follow-on specification may change. **Why this priority**: Agent activity is a second thing the person may want to see. It must not become user-owned work. -**Independent Test**: Turn Agents as Animals on with one Claude Code session running. An Animal appears that cannot be opened as a Focus. Turn the setting off. That Animal is gone and the Focus Animals remain. +**Independent Test**: With the ranch listening and Agents as Animals on, have one ongoing Claude Code session emit a Hook Firing that establishes or updates the session. Its Animal appears and cannot be opened as a Focus. Turn the setting off. That Animal is gone and the Focus Animals remain. **Acceptance Scenarios**: @@ -94,7 +117,7 @@ The person can turn on Agents as Animals. Each running Claude Code Agent Session - The first launch creates one example Focus so the ranch is not empty. A marker stops that example from returning after the person deletes every Focus. - A missing or corrupt Timer sidecar is treated as no Timer. It does not block the Focus file. -- Going Over Limit still saves the Focus or Task. The tray icon turns red, and one notification fires for that crossing. +- Going Over Limit still saves the Focus or Task. The tray icon turns red. If the relevant notification is enabled, it fires once for that crossing; if disabled, no notification fires. - Only the primary display is enabled until the person enables more in Settings. Animals do not wander through gaps between displays. - Settings changed in the app apply without a restart. A hand-edit of the settings file applies on the next launch. - On Windows the ranch builds and stores data under the platform data directory. It does not receive Hook Firings there. @@ -120,9 +143,11 @@ The person can turn on Agents as Animals. Each running Claude Code Agent Session ### Limits -- **FR-013**: Task Timers MUST stay indexed to Task position. A hand-edit that reorders or inserts Tasks can move a Timer onto another Task. That drift is not repaired today. -- **FR-014**: A Hook Firing that arrives late MUST still be eligible to apply. The ranch MUST NOT yet tell a turn that ended from a turn that died as two different Firings. A session change MUST be learned by reading the session list again. -- **FR-015**: The ranch MUST NOT remove an older direct hook entry left in Claude's settings by a previous build. New hook delivery MUST go through the Claude plugin and the stable client under the Ranch data directory. +FR-013 through FR-015 describe current limitations as observations. Follow-on specifications may change this behavior. + +- **FR-013**: Task Timers are currently indexed to Task position. A hand-edit that reorders or inserts Tasks can move a Timer onto another Task. That drift is not repaired today. +- **FR-014**: A Hook Firing that arrives late is currently eligible to apply. The ranch does not yet tell a turn that ended from a turn that died as two different Firings. A session change is learned by reading the session list again. +- **FR-015**: The ranch currently leaves an older direct hook entry in Claude's settings when a previous build wrote it. New hook delivery goes through the Claude plugin and the stable client under the Ranch data directory. - **FR-016**: macOS MUST be the design target. Windows and Linux packages MUST still build. Hook delivery MUST NOT be available on Windows. - **FR-017**: The ranch MUST NOT demand attention except through a notification the person has turned on, or through a window the person opened. @@ -151,8 +176,8 @@ The person can turn on Agents as Animals. Each running Claude Code Agent Session - **SC-001**: A person can name their open Focuses by looking at the overlay, without opening another tool. - **SC-002**: A person can add, Complete, and Delete a Task, and start or Clear a Timer, from the Focus Animal's card, and the Focus file matches. - **SC-003**: A hand-edit of a Focus file shows on the overlay within about a second. -- **SC-004**: Going past a Limit still saves, warns once, and does not count Agent Sessions. -- **SC-005**: With Agents as Animals off, no Agent Session Animal is shown. With it on, those Animals are visible and cannot be edited as Focuses. +- **SC-004**: Going past a Limit still saves and turns the tray icon red. If the relevant notification is enabled, it fires once for that crossing; if disabled, no notification fires. Agent Sessions do not count toward Limits. +- **SC-005**: With Agents as Animals off, no Agent Session Animal is shown. With it on, ongoing sessions observed through Hook Firings are visible and cannot be edited as Focuses. - **SC-006**: The running app makes no outbound product network call. ## Sources diff --git a/specs/003-ranch-today/tasks.md b/specs/003-ranch-today/tasks.md new file mode 100644 index 0000000..68e2a3d --- /dev/null +++ b/specs/003-ranch-today/tasks.md @@ -0,0 +1,204 @@ +# Tasks: Ranch Today Baseline Validation + +**Input**: Design documents in `specs/003-ranch-today/`: [plan](plan.md), [spec](spec.md), [research](research.md), [data model](data-model.md), [contracts](contracts/current-behavior.md), [quickstart](quickstart.md). + +**Status**: Draft execution plan, generated 2026-10-17. The specification remains Draft. Generating this list does not approve product changes or certify current behavior. + +**Scope**: Validate and document existing behavior. No product implementation, dependency changes, new tests, migrations, generated-type edits, or fixes for FR-013–FR-015. Existing tests are reused as evidence. New runtime work needs its own approved scope. + +**Organization**: Setup → foundation → five independently verifiable user stories → cross-cutting reconciliation. Every task starts unchecked. Mark an execution task done when its stated work and honest result record are complete; a recorded failure or unverified check is not a passed acceptance criterion. + +**Execution record (2026-10-17)**: The current-main automated gate passed. Native/platform observations remain unverified as detailed in [the pass record](validation/pass-record.md). Checked tasks record completed evidence assessment, not passed product acceptance; all six success criteria still need end-to-end proof. + +## Format and Paths + +Tasks use `- [ ] Tnnn [P?] [USn?] description`. `[P]` marks independent source checks with distinct output files after the foundation completes. Other tasks run sequentially. + +All file paths below are relative to the repository root. Execution creates one shared `specs/003-ranch-today/validation/pass-record.md` and one evidence note per story (`us1.md` through `us5.md` in the same directory). These outputs are not created by task generation. + +Evidence notes record source pointers, commit/platform, exact commands and exit statuses, observed outcomes, pass/fail/unverified status, and discrepancies. Never substitute source inspection or past CI for a fresh test or native result. Do not include personal data, credentials, raw transcripts, or machine-specific scratch paths in committed evidence. + +## Constitution Compliance Check + +| Principles | Execution constraint | +|---|---| +| I — Local state | Use synthetic isolated data; inspect atomic-write/sidecar coverage; no personal work/configuration writes or outbound product feature. | +| II — Domain separation | Validate Focus/Task/Timer independently from Agent activity; only the flat render contract joins them. | +| III — Typed boundaries | Reuse existing source owners and tests; generated contracts remain generated. No new implementation is authorized. | +| IV — Explicit integrations | Toggle is not install. Distinguish validated configuration from observed delivery; live checks use isolated configuration and explicit installation. | +| V — Observable completion | Bound tasks by evidence outputs; synchronize with current main before the gate; retain failures and unverified outcomes. Shipping completion still requires review, green CI, and merge. | +| VI — Authority | Keep Draft status; accepted ADRs outrank observed shortcomings. Record ADR-0002 drift and route follow-ons without silently changing accepted decisions. | + +**Result**: PASS for this documentation/validation task design; no exception is requested. Existing runtime drift is not declared compliant. These tasks may collect baseline evidence without promoting a Draft spec to governing implementation authority. + +## Phase 1: Setup + +**Purpose**: Establish the scope and disposable validation environment; reuse the existing project. + +- [X] T001 Create `specs/003-ranch-today/validation/pass-record.md` with the input artifact versions, current commit/branch, relation to current main, scope exclusions, and Constitution I–VI check; preserve all existing dirty work and arrange a synchronized isolated checkout if necessary for the later gate rather than resetting or stashing it. +- [X] T002 Follow the isolation setup in `specs/003-ranch-today/quickstart.md` and record the procedure in `specs/003-ranch-today/validation/pass-record.md`: use a fresh short temporary root with separate `ADHD_RANCH_HOME` and `CLAUDE_CONFIG_DIR`, synthetic data only, and one running Ranch instance; check first-launch example creation and that deleting it/restarting does not recreate it. + +## Phase 2: Foundational + +**Purpose**: Establish shared authority, evidence conventions, and automated results before any story validation. + +- [X] T003 Reconcile `specs/003-ranch-today/contracts/current-behavior.md` and `specs/003-ranch-today/research.md` against the selected validation commit and accepted ADRs 0001–0003; record any staleness in `specs/003-ranch-today/validation/pass-record.md`, retaining the distinction between current observations, accepted decisions, Draft follow-ons, and unresolved evidence. +- [X] T004 After confirming synchronization with current main, run `rtk task check` from the repository root using `Taskfile.yaml`; record command, commit, exit status, and any failures in `specs/003-ranch-today/validation/pass-record.md`. Do not weaken gates or edit generated types to get green; report failures for separately scoped resolution. This single gate supplies the existing automated results referenced by story notes; rerun only after relevant changes or unresolved failures justify it. + +**Checkpoint**: Evidence setup exists and the automated gate has an honest result. Failures must remain visible; no story may claim coverage from a failed or unexecuted test. + +## Phase 3: US1 — Glance and Know What Is Open (P1, MVP) + +**Goal**: Establish that Focus Animals are useful, ambient reminders on enabled displays. + +**Independent test**: With two synthetic Focuses, identify both by their visible Pig labels, verify empty-space click-through, drag/toss/Gather, and observe no unsolicited attention. + +- [X] T005 [P] [US1] Review `crates/commands/src/focus_animals.rs`, `crates/commands/src/render_scene.rs`, `crates/commands/tests/render_scene_contract.rs`, and `src/lib/animalMovement.test.ts`; write `specs/003-ranch-today/validation/us1.md` with source/coverage pointers for the model constraints “Species is Pig; Motion is Walking or Resting.”, “Size is fixed or linearly sampled over time.”, optional `regionId`, and “Movement and sprites consume neither domain types nor source discriminators.”; distinguish generated wire shape from native behavior. +- [X] T006 [US1] Execute V3 in `specs/003-ranch-today/quickstart.md` using two fresh synthetic Focuses; record labels/one Pig per Focus, drag/toss, Gather, primary-only defaults, display enablement/no gap traversal, empty-space click-through, and ambient attention observations in `specs/003-ranch-today/validation/us1.md`. Record unavailable multi-display/native checks as unverified rather than inferred from tests (SC-001). + +**Checkpoint**: US1 has source evidence plus explicit native results or remaining gaps; this is the suggested MVP validation scope. + +## Phase 4: US2 — Work a Focus from Its Animal (P1) + +**Goal**: Verify card editing and Timer ownership without changing their implementation. + +**Independent test**: Open one Focus card, add/edit/Complete/Delete Tasks, start/Clear Timers, compare files, and independently exercise Focus versus Task expiry. + +- [X] T007 [P] [US2] Review `crates/domain/src/focus.rs`, `crates/domain/src/parse.rs`, `crates/commands/src/focus.rs`, `crates/commands/src/timers.rs`, and `src/components/AnimalDetail.test.tsx`; record source/coverage in `specs/003-ranch-today/validation/us2.md` for “App writes reject blank text.”, “parser requires frontmatter with `id` and `title`.”, optional `timer`, `status: Running / Expired`, and one-owner `Focus { focus_id }` / `Task { focus_id, index }` addressing. Treat positional identity as an observation, not a constraint to preserve. +- [X] T008 [US2] Execute V1 card/CRUD actions from `specs/003-ranch-today/quickstart.md`; record title rename, duplicate and delete, Task add/edit/Complete/undo/Delete, blank-input rejection, matching Markdown, and outside-click/Escape closure in `specs/003-ranch-today/validation/us2.md`. Verify “Editing text preserves completion.” and distinguish Complete/Delete from Timer Clear (SC-002). +- [X] T009 [US2] Execute V1 start/restart/Clear and saved-chip checks; inspect `crates/domain/src/settings.rs` and `src-tauri/src/app/settings_workflow.rs` against “Saved custom minutes are positive, unique, and exclude built-ins 10/30/60.” Record shared pickers, restart persistence, owning sidecars, and chip removal leaving running Timers/built-ins intact in `specs/003-ranch-today/validation/us2.md`. +- [X] T010 [US2] Execute V1 short-Timer expiry/revival checks and compare fixture work files before/after expiry; record Focus growth/resting/ghostly/away/tray behavior, allowed notifications, and timer-only persistence in `specs/003-ranch-today/validation/us2.md`. Verify “Adding a Task clears an Expired Focus Timer (Revive), never a Task Timer.” and “Task Timer expiry changes neither projection nor tray membership.” + +**Checkpoint**: Editing, Timer selection, and both expiry paths have independent results; no new model/service/UI work is introduced. + +## Phase 5: US3 — Run the Ranch from the Tray (P2) + +**Goal**: Verify tray actions, live Settings, and soft Limits. + +**Independent test**: Create, Gather, cancel/confirm deletion, and open Settings from the tray; lower Limits and cross them without losing writes. + +- [X] T011 [P] [US3] Review `src-tauri/src/app/tray.rs`, `crates/domain/src/settings.rs`, `crates/domain/src/caps.rs`, `crates/commands/src/caps.rs`, and `src-tauri/src/app/settings_workflow.rs`; record coverage in `specs/003-ranch-today/validation/us3.md`, including defaults 5/7 and the model constraint “Completed Tasks count because all stored Tasks are counted; writes above a threshold remain permitted.” Agent Sessions are excluded from the evaluator. +- [X] T012 [US3] Execute V4 tray/Settings actions from `specs/003-ranch-today/quickstart.md`; record New Focus, Gather, delete cancellation/confirmation, Agents toggle, Settings (Preferences menu naming on macOS), quit, immediate application of app edits, and restart persistence in `specs/003-ranch-today/validation/us3.md`. +- [X] T013 [US3] Execute V4 Focus and Task Limit crossings with notification settings enabled and disabled; record successful over-threshold writes, red tray state, completed-Task counting, and one allowed notification per crossing without repeated notifications while above in `specs/003-ranch-today/validation/us3.md` (SC-004). Cross-reference the separate Agent exclusion proof from US5 when available; do not require US5 to validate Focus-only crossings. + +**Checkpoint**: Tray/Settings behavior and Limit crossings have results; live Agent exclusion is separately traced to US5. + +## Phase 6: US4 — Hand-Edit the Markdown (P2) + +**Goal**: Verify canonical file ownership, external edit latency, and safe optional sidecars. + +**Independent test**: Append/Complete a checkbox in a fixture file, measure save-to-card visibility, and verify work remains usable across restart and malformed optional sidecars. + +- [X] T014 [P] [US4] Review `crates/domain/src/parse.rs`, `crates/storage/src/focus_store.rs`, `crates/storage/src/watcher.rs`, and `src-tauri/src/app/paths.rs`; record coverage in `specs/003-ranch-today/validation/us4.md` for “Missing/corrupt optional sidecars load as no Timer.”, nonempty checkbox parsing, derived `focus_id:index` identity with “no stable persisted Task ID.”, and current data-root resolution. Record FR-013 as an observation; do not add stable IDs, reorder repair, or a migration. +- [X] T015 [US4] Execute V2 and the V1 disposable-sidecar checks from `specs/003-ranch-today/quickstart.md`; record external checkbox add/Complete, measured latency against about one second, restart durability, Settings hand-edit applying on next launch, and missing/corrupt optional sidecar behavior in `specs/003-ranch-today/validation/us4.md` (SC-003). Preserve fixture Markdown and distinguish measured UI timing from watcher debounce. + +**Checkpoint**: External editing is measured; Task Timer drift remains a documented limitation, not an acceptance promise. + +## Phase 7: US5 — See an Agent without Tracking It as Work (P3) + +**Goal**: Verify opt-in observation, explicit installation, delivery diagnostics, and domain independence. + +**Independent test**: Observe one session after a Firing, toggle its Animal on/off, confirm it cannot open a Focus card or affect work/Limits, and distinguish healthy configuration from delivery. + +- [X] T016 [P] [US5] Review `crates/domain/src/session/agent_session.rs`, `crates/domain/src/agents/hooks.rs`, `crates/storage/src/agent_hooks/journal.rs`, `crates/storage/tests/agent_hook_socket.rs`, `src-tauri/src/app/claude_plugin.rs`, `src-tauri/src/app/claude_hook.rs`, and `src/components/App.test.tsx`; record existing coverage in `specs/003-ranch-today/validation/us5.md` for `activity: Working / Idle`, `action: Start / Working / Idle / End`, optional `session_id`/`pen`, unchanged Firings, bounded absent-app delivery, ephemeral sessions, and configuration health versus observed delivery. +- [X] T017 [US5] Execute the non-installing V5 UI checks from `specs/003-ranch-today/quickstart.md`; record default-off behavior, enabling without silent installation, and Install Hooks dialog/action separation in `specs/003-ranch-today/validation/us5.md`. Use isolated automated plugin install/repair and delivery results from T004; never present those fixtures as real-session evidence. +- [X] T018 [US5] Attempt the optional V5 live check only in an independently usable disposable Claude configuration, with matching Ranch/Claude environment values and explicit Install Hooks; otherwise record that live evidence is unverified and why. Open the Agent Hooks window and verify that wiring/configuration health, the live session roster, and recent Hook Firings are visible, including a Firing that changed nothing. In `specs/003-ranch-today/validation/us5.md`, separately record those window checks, plugin health, a post-listener Firing/unchanged repeat, non-editable Agent Animal, unchanged work files/Limits, and toggle hiding Agents while retaining Focuses/plugin (FR-011, SC-004, SC-005). Mark any unavailable window or live checks unverified. Do not read personal transcripts, borrow credentials, perform cold-start census, or treat Windows delivery as supported. + +**Checkpoint**: Automated, UI, and live evidence are distinguished. Unavailable live delivery leaves its acceptance claim open. + +## Phase 8: Polish and Cross-Cutting Reconciliation + +**Purpose**: Consolidate truthful baseline evidence without turning gaps into feature implementation. + +- [X] T019 Reconcile V7 observations with `specs/003-ranch-today/research.md`, `issues/056-task-timer-binding.md`, `issues/059-self-describing-hook-frame.md`, `issues/060-session-staleness-sweep.md`, `issues/061-hook-change-events.md`, and `issues/062-stable-hook-client-path.md`; record current status and owning Draft follow-ons in `specs/003-ranch-today/validation/pass-record.md`. Explicitly retain ADR-0002 accepted-direction/current-code drift and FR-013–FR-015 observation status; do not promote issue proposals to requirements or implement their fixes. +- [X] T020 Execute the V6 scoped boundary/non-goal review and, where available, packaged-process network observation in `specs/003-ranch-today/quickstart.md`; record tools, exercised actions, results or unverified gaps, and macOS/Windows/Linux evidence in `specs/003-ranch-today/validation/pass-record.md` (SC-006). Use `Taskfile.yaml`, `.github/workflows/windows.yml`, and `.github/workflows/release.yml` to distinguish compile, package, and native proof; run relevant platform gates only when changes require them, and do not trigger release workflows. Vite/explicit Claude CLI activity is reported separately from product runtime traffic. +- [X] T021 Consolidate `specs/003-ranch-today/validation/us1.md` through `specs/003-ranch-today/validation/us5.md` into a full FR/SC evidence index in `specs/003-ranch-today/validation/pass-record.md`; classify every entry as passed, failed, unverified, or observation, link the exact supporting task/result, and route new gaps to narrow follow-on issues without silently rewriting the spec, accepted ADRs, or acceptance bar. +- [X] T022 Verify links, checklist format, task/result consistency, whitespace, and unchanged unrelated files for `specs/003-ranch-today/tasks.md` and `specs/003-ranch-today/validation/`; record the final Constitution I–VI check, remaining acceptance gaps, and completion limits in `specs/003-ranch-today/validation/pass-record.md`. Do not claim the product baseline fully verified with failed/unverified criteria, or claim shipped completion without independent review, green CI, and merge. + +## Coverage Index + +| Requirement / outcome | Tasks | +|---|---| +| FR-001, FR-002 | T007–T008, T010, T014–T015 | +| FR-003 | T007, T009–T010 | +| FR-004, FR-009 | T005–T006, T012 | +| FR-005 | T008, T016, T018 | +| FR-006, FR-008 | T011–T012, T015 | +| FR-007 | T011, T013, T016, T018 | +| FR-010, FR-011 | T016–T018 | +| FR-012, FR-017 | T006, T020 | +| FR-013 | T014, T019 (observation only) | +| FR-014, FR-015 | T016, T019 (observation only) | +| FR-016 | T020 (separate platform evidence; no fabricated build result) | +| FR-018, FR-019, FR-020 | T010, T018, T020 | +| FR-021, FR-022 | T005–T006, T011–T012, T016, T020 | +| SC-001 | T006 | +| SC-002 | T008–T010 | +| SC-003 | T015 | +| SC-004 | T013, T018 | +| SC-005 | T017–T018 | +| SC-006 | T020 | + +T021 reconciles all entries; T022 checks the final evidence and governance claims. + +## Dependencies and Execution Order + +```text +T001 → T002 → T003 → T004 + | + +→ US1: T005 → T006 + +→ US2: T007 → T008 → T009 → T010 + +→ US3: T011 → T012 → T013 + +→ US4: T014 → T015 + +→ US5: T016 → T017 → T018 + | +all story results → T019 → T020 → T021 → T022 +``` + +- All stories depend on the foundation, not on another story's successful outcome. Create fresh story-specific synthetic state as needed; do not rely on a previous story's mutations. +- After T004, T005/T007/T011/T014/T016 can run together: they read source and write different story notes. They reference T004's results without running concurrent generated-type/build gates. +- Native tasks share the foreground app/OS surface and must run one at a time. Prefer priority order US1 → US2 → US3 → US4 → US5; independent story fixtures allow a different order. +- US3's Focus-only crossing result stands alone; its full Agent exclusion claim incorporates T018. US5 uses its own fixture and does not depend on T013. +- A failed gate does not prohibit read-only diagnosis or recording native observations; it prohibits calling failed coverage passed or claiming readiness. + +## Parallel Examples per Story + +These are scheduling examples, not instructions to spawn agents during task generation. + +| Story | Safe parallel example after T004 | Sequential native follow-through | +|---|---|---| +| US1 | T005 alongside T007 (different notes) | T006 after T005 and when foreground app is free | +| US2 | T007 alongside T011 | T008 → T009 → T010 after T007 | +| US3 | T011 alongside T014 | T012 → T013 after T011 | +| US4 | T014 alongside T016 | T015 after T014 | +| US5 | T016 alongside T005 | T017 → T018 after T016 | + +## Implementation Strategy + +**MVP first**: Complete T001–T006 and stop to assess the ambient Focus reminder. This establishes only US1, not Timer, tray, hand-edit, or Agent acceptance. + +**Incremental validation**: Add US2, then US3, US4, and US5; preserve separate story results and execute shared native work serially. Reuse T004's unchanged-code automated gate rather than adding new tests or rerunning whole suites per story. + +**Stop condition**: Finish T019–T022 with all evidence reconciled and remaining gaps explicit. A finished evidence pass may still have unverified product criteria. No runtime fix, new abstraction, approval-status change, PR, merge, or release is implied by checking off this documentation workflow. + +## Phase 9: Convergence + +**Assessment (2026-10-17):** 28 FR/SC entries, 16 acceptance scenarios, six plan decisions, four validation slices, and Constitution I–VI checked. Seven partial acceptance-evidence gaps remain: five HIGH, two MEDIUM. Existing implementation and automated proof do not establish the native results below. No additional confirmed code defect or constitutional violation was established by this bounded assessment. + +**Constitution compliance:** This phase preserves local synthetic state, independent domains, typed boundaries, and explicit integration actions (I–IV). It requires actual acceptance evidence before completion claims (V), preserves Draft status and source classifications (VI), and grants no exception. FR-013–FR-015 remain observations; their fixes and stale follow-on issue contracts stay outside this baseline. + +**Owner execution direction (2026-10-17):** Ship the existing implementation and these baseline documents through independent review, green CI, merge, and release before the owner performs native testing. T023–T028 remain open for that later test pass; T029 still requires successful matching platform packages. This direction does not mark acceptance passed, promote Draft artifacts, or authorize implementing Draft follow-ons. See the [owner direction record](validation/pass-record.md#owner-direction--ship-before-later-native-testing-2026-10-17). + +**Completion rule:** These tasks close acceptance gaps left open by the availability assessment in T001–T022. Mark a task complete only after its stated proof is obtained and recorded. If native access, a disposable Claude setup, inspection tools, or a target platform is unavailable, record the limitation and leave the task unchecked. Do not replace observations with source inspection, historical CI, or another note that the check was unavailable. A failed observation remains an open acceptance gap and needs separately scoped resolution; this phase authorizes no product changes, new test infrastructure, or release publication. + +- [ ] T023 [US1] **HIGH — F1:** Execute V3 in `specs/003-ranch-today/quickstart.md` with native app control and isolated synthetic data; observe first-launch example creation and non-reappearance after deletion/restart, then identify two Focuses by visible labels. Verify one Pig per Focus, drag/toss/Gather to primary, enabled-display boundaries/no gaps, empty-space OS click-through, and no unsolicited attention. Record platform, source revision, actions and actual outcomes in `specs/003-ranch-today/validation/us1.md` and the corresponding `validation/pass-record.md` rows; leave unobserved items open per SC-001, US1/AC1–AC3, FR-004, FR-009, FR-017, FR-021, and plan: ambient-shell validation (partial). +- [ ] T024 [US2] **HIGH — F2:** Complete native V1 from `specs/003-ranch-today/quickstart.md`: Focus rename/duplicate/delete, Task add/edit/Complete/undo/Delete and blank rejection, outside-click/Escape closure, and matching canonical files. Verify Focus/Task Timer start/restart/Clear, shared saved chips across pickers/restart, chip removal preserving running Timers, Focus growth/expiry appearance/tray membership, add-Task revival, and Task expiry independence. Compare synthetic work files across expiry to establish timer-only writes. Record actual observations and file outcomes in `specs/003-ranch-today/validation/us2.md` and its `validation/pass-record.md` rows per SC-002, US2/AC1–AC5, FR-001–FR-003, FR-005, and plan: files-and-Timers validation (partial). +- [ ] T025 [US4] **HIGH — F3:** Execute native V2 and the disposable-sidecar cases from `specs/003-ranch-today/quickstart.md`; externally add/Complete checkbox Tasks and measure save-to-visible-card elapsed times against the approximately one-second outcome. Verify native restart durability, hand-edited Settings applying on next launch, and usable Focuses with missing/corrupt optional sidecars. Record measurement method, actual times, revision/platform, and results in `specs/003-ranch-today/validation/us4.md` and its `validation/pass-record.md` rows; do not substitute debounce duration for end-to-end timing or repair positional Timer drift per SC-003, US4/AC1, FR-001, FR-008, and plan: hand-edit validation (partial). +- [ ] T026 [US3] **HIGH — F4:** Execute native V4 in `specs/003-ranch-today/quickstart.md`: verify tray New Focus, Gather, delete cancellation/confirmation, Settings/Preferences naming, quit, immediate Settings application and restart persistence. Verify defaults 5/7, then cross lowered Focus/Task Limits while retaining writes, observe the red tray icon and one enabled notification per crossing without repeats, repeat with notifications disabled, and confirm completed Tasks count. Record evidence in `specs/003-ranch-today/validation/us3.md` and its `validation/pass-record.md` rows per SC-004, US3/AC1–AC3, FR-006–FR-008, and plan: ambient-shell validation (partial). T028 supplies the separate live-Agent exclusion proof; SC-004 cannot close until both portions are supported. +- [ ] T027 **HIGH — F5:** Obtain a matching packaged Ranch build using existing `Taskfile.yaml` build commands if needed, then execute V6 from `specs/003-ranch-today/quickstart.md` with process-scoped network inspection while exercising the core synthetic scenarios. Record build identity, platform, inspection tool, process, observation window, exercised actions, and actual connection/listener results in `specs/003-ranch-today/validation/pass-record.md`; separate Vite traffic and explicit Claude CLI effects from product runtime. Source searches alone do not close this task per SC-006, FR-012, and plan: runtime-boundary validation (partial). +- [ ] T028 [US5] **MEDIUM — F6:** Execute native/live V5 from `specs/003-ranch-today/quickstart.md` in an independently usable disposable Claude configuration with matching Ranch/Claude environment values and an explicit Install Hooks action. Verify default-off and opt-in visibility, no silent installation, a post-listener session Firing, Agent non-editability, unchanged Focus/Task files and Limits, and toggle-off hiding Agents while retaining Focus Animals/plugin. Open Agent Hooks and observe wiring/configuration health, live sessions, and recent Firings including an unchanged repeat; distinguish configuration health from real delivery. Record actual results in `specs/003-ranch-today/validation/us5.md` and its `validation/pass-record.md` rows without borrowing credentials or reading personal transcripts per SC-005, SC-004 (Agent exclusion), US5/AC1–AC4, FR-010–FR-011, and plan: Agent-boundary validation (partial). +- [ ] T029 **MEDIUM — F7:** Obtain successful Windows and Linux package-build evidence matching the assessed runtime source, using the existing non-publishing Windows workflow in `.github/workflows/windows.yml` and package commands/platform prerequisites defined by `.github/workflows/release.yml`. Use an appropriate target environment or matching recorded build results; do not create new pipelines or dispatch publishing release workflows. Record source/build identity, target, commands, exit status, and package artifacts in `specs/003-ranch-today/validation/pass-record.md`; workflow configuration or a compile-only result is not package proof, and Windows hook delivery remains unsupported per FR-016 and plan: retained platform compatibility (partial). + +**Execution and evidence:** Keep native work serial on the shared OS surface. Each task updates its story note where applicable and the shared evidence index, retaining earlier results as historical observations. T026's Focus/Task checks can finish independently; its Agent comparison is supplied by T028. Before declaring convergence, reconcile every affected FR/SC and acceptance scenario to the obtained proof. Preserve the existing current-source automated gate result unless relevant source changes or failures justify rerunning it. If required access remains unavailable, keep this phase open rather than cycling another implement/converge pass as proof. + +Path clarification for this phase: shortened `validation/pass-record.md` references in T023–T026 and T028 mean `specs/003-ranch-today/validation/pass-record.md`. diff --git a/specs/003-ranch-today/validation/pass-record.md b/specs/003-ranch-today/validation/pass-record.md new file mode 100644 index 0000000..8f96e7b --- /dev/null +++ b/specs/003-ranch-today/validation/pass-record.md @@ -0,0 +1,209 @@ +# Ranch Today Validation Pass + +**Date**: 2026-10-17 | **State**: Convergence attempt incomplete; Linux package attempt failed; native acceptance remains open; no shipped completion claimed. + +Runtime source commit: `a48525d9a89555bf9bc925a20d626c0dc634b4ce` (local main equals origin/main after a successful fetch). Tests run in a temporary detached worktree at that commit. The working checkout contains only unrelated/documentation edits, preserved in place. The clarified 003 documents guide this pass but remain Draft. + +## Initial scope and setup (T001–T002) + +Reuse existing code and tests. No implementation, new tests, dependency upgrades, migration, generated-type edits, hook fixes, PR, or release. Fresh short temporary Ranch data and empty Claude configuration directories were created outside the repository. Temporary paths and raw logs are not committed. Native computer control is disabled in this session; browser control cannot operate the native Ranch windows, tray, OS click-through, or notifications. No Ranch instance was running at process inventory. No app was launched, plugin installed, personal configuration copied, credential borrowed, or transcript read. + +T002 fixture setup: **PASS**. Native first-launch example/delete/restart observation: **UNVERIFIED** because native control is unavailable. Existing seed tests will provide separate automated evidence if the gate passes. + +## Input revisions at start + +| Artifact | SHA-256 | +|---|---| +| `specs/003-ranch-today/spec.md` | `bd59188787842ae9b95fd0e8b4a02acd128cbe2ca2c969ad60508ac6ad08b5cb` | +| `specs/003-ranch-today/plan.md` | `46df8f3cd6ec862e71897c4d46c005f836ffc90ea36c7ae04b90d584d1b92954` | +| `specs/003-ranch-today/tasks.md` | `a4b963f32e6de17cb2ad6e543ad5bb949df62cea105fce488a1a58e00a7a15fe` | +| `specs/003-ranch-today/research.md` | `4e508efbade9bb0e2e1da7262a9fd07adeabb7ad5f69037dd93b4a5c86e9fa57` | +| `specs/003-ranch-today/data-model.md` | `30c6242a0aed24df0d054f518baa025f22a54c2b33ab520c73039d9ccc201a46` | +| `specs/003-ranch-today/contracts/current-behavior.md` | `f72ca3581d92cb35d4d973c8dc0ccf178314a957a58313af9c6a704fe07b59bb` | +| `specs/003-ranch-today/quickstart.md` | `7b5efe4b9f55d6a415c053130f9273384241e89e34d3bd2ab72f521235cc756f` | +| `.specify/memory/constitution.md` | `c40cb396de6834eff9e65f8d94caf69e7644ae783841eeedb395760ae48cba69` | + +The tasks hash identifies the pre-execution checklist; task markers change as evidence is recorded. + +## Constitution check + +| Principle | Result for this validation pass | +|---|---| +| I | Isolated synthetic data; no personal-data writes or new runtime behavior. | +| II | Focus and Agent evidence stay separate; their accepted renderer seam is retained. | +| III | No source/generated contract changes; existing pure-rule and boundary tests only. | +| IV | No implicit installation; configuration and delivery proof remain distinct. | +| V | Current-main gate passed; native gaps and failures remain visible; no shipping claim. | +| VI | Draft status retained; accepted ADR direction distinguished from current code and follow-on proposals. | + +## Automated gate (T004) + +**PASS** — `rtk task check`, exit 0, 133.93 seconds, on synchronized runtime commit `a48525d9a89555bf9bc925a20d626c0dc634b4ce` in the detached validation checkout. Normal Rust suites passed 335 tests; Vitest passed 170 tests across 26 files. Generated-export checks also passed. This ran Rustfmt, debug/release Clippy, Biome, unused dependency/code checks, IPC/CSS checks, TypeScript checking, Rust unit/integration tests, Vitest, and generated-type drift. The checkout remained clean afterward, including manifests, lockfiles, and generated types. No gates were suppressed. Raw logs were inspected outside the repository; summaries below retain fresh results without temporary paths. + +- running 59 tests +- test result: ok. 59 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.20s +- running 2 tests +- test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +- running 112 tests +- test result: ok. 112 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +- running 96 tests +- test result: ok. 96 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.27s +- running 9 tests +- test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 5.03s +- running 4 tests +- test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.03s +- running 53 tests +- test result: ok. 53 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.07s +- Test Files 26 passed (26) +- Tests 170 passed (170) +- Duration 2.40s (transform 1.06s, setup 1.37s, collect 2.76s, tests 4.84s, environment 8.54s, prepare 1.55s) +- running 136 tests +- test result: ok. 136 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.14s +- running 0 tests +- test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +- running 68 tests +- test result: ok. 68 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.24s +- running 2 tests +- test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +- running 0 tests +- test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + +## Source reconciliation and setup verification (T003) + +**PASS** for source freshness: the fetched main commit matches the planning runtime target. ADR-0001, ADR-0002, and ADR-0003 are Accepted. ADR-0003 refines the renderer placement from ADR-0001. ADR-0002's stamped frames/change events remain accepted direction, not completed implementation: see the known-observations section to be consolidated under T019. Draft specs 004–008 and local issue proposals do not add requirements to 003. No artifact or code change is required by this reconciliation. + +Setup verification: Git repository confirmed; `.gitignore` covers 19 checked generated, dependency, environment, backup, editor, and temporary-path examples. No Docker, ESLint, Prettier, Terraform, or Helm configuration was detected at the root. The npm package is private, so no publish ignore is required. No ignore/configuration files changed. + +## Toolchain + +macOS 26.6.2 arm64; rustc 1.99.0, cargo 1.99.0, Node v24.21.0, npm 12.0.2, Task 3.53.1. These are the execution environment, not proposed project minimums. Runtime source/manifests/lockfiles in the working checkout have no edits; the isolated checkout tests their current-main versions. Build output, dependency installation, and generated-type checks stay in the temporary checkout/target directory. + +## Known observations and follow-on routing (T019) + +These are source observations, not failed preservation tests or approved alternatives to Accepted ADRs. + +| Entry | Current evidence | Follow-on context | +|---|---|---| +| FR-013 | Task Timers are positional arrays; parser identity is `focus_id:index`; arbitrary external insertion/reordering has no stable binding repair. | [004](../../004-task-timer-hand-edits/spec.md), [056](../../../issues/056-task-timer-binding.md) remain draft/proposal context. | +| FR-014 | Client/server frame is verb plus payload; LiveSessions applies arrival order; Stop/StopFailure both map to Idle; host emits unit invalidations and the frontend refetches. ADR-0002 accepts stamped frames and change-carrying events, so its target/checklist cannot certify current implementation. | [005](../../005-late-hook-frame/spec.md), [059](../../../issues/059-self-describing-hook-frame.md); [006](../../006-unheard-turn-ends/spec.md), [060](../../../issues/060-session-staleness-sweep.md) for missed-event recovery; [061](../../../issues/061-hook-change-events.md) for change events. | +| FR-015 | Current plugin/client owner does not edit older direct entries; stable client sits directly under the Ranch root. No personal configuration was inspected to establish whether such entries exist on this machine. | [007](../../007-one-hook-delivery/spec.md), [062](../../../issues/062-stable-hook-client-path.md). | + +Before follow-on implementation, refresh two stale issue contracts: 061 still names this observational baseline's FR-014 as its owning build specification; it needs an approved build contract aligned with ADR-0002. 062 describes the old direct-settings installer and a proposed `bin/` layout, whereas current code uses a Claude-managed plugin and a client directly under the Ranch data root. Its historical machine/log examples are not fresh evidence. These corrections are routed to the existing issues; neither their implementation nor personal hook cleanup is authorized by this pass. + +## Boundaries, platform scope, and runtime gaps (T020) + +**PASS, scoped source review:** inspected `src-tauri/src/ui_bridge/mod.rs`, host composition, Focus/Timer workflows, Agent adapters, manifests, and Tauri configuration. The exposed application boundary is typed Tauri IPC; user work writes route through explicit Focus operations, seed setup, filesystem hand-edits, and timer-state expiry. Agents do not own Focus writes, editing, or Limits. Species is Pig and the only Harness module is Claude Code. No sync/import/multi-user service, Wrangle action, automatic Task completion/Focus merging, or Harness notification forwarding was found in this scope. + +A source search across Rust/TypeScript runtime files under `crates/`, `src/`, and `src-tauri/src/` for `fetch(`, XMLHttpRequest, WebSocket, reqwest, hyper, TCP listeners/streams, ureq, telemetry, Sentry, and provider API-key symbols returned no matches (rg exit 1, expected for no matches). This is bounded source evidence, not proof of every dependency's runtime behavior. Tauri's localhost Vite dev URL is development infrastructure; packaged assets use `frontendDist`. Explicit plugin install delegates marketplace operations to the local Claude CLI, whose external effects are separate from Ranch product runtime traffic. + +**UNVERIFIED:** SC-006 packaged-process network observation was not run. No native app was launched or core scenarios exercised in a packaged process; availability of a network inspection utility alone is not runtime evidence. Native ambient/attention/notification checks are also unverified. + +**Platform evidence:** current macOS host passed debug/release Clippy and host tests in T004; frontend production build passed. Actual macOS bundling/native behavior was not tested. Windows cross-check, Windows installers, and Linux packages were not run; this documentation-only pass changes no platform source and does not trigger release workflows. [Windows workflow](../../../.github/workflows/windows.yml) defines manual x64/ARM64 NSIS builds; [release matrix](../../../.github/workflows/release.yml) defines Linux AppImage/deb and other packages. Configuration is not a fresh package-build result. Windows hook delivery is unsupported by the Unix-gated implementation. + +## Evidence index (T021) + +Every tracked entry is assessed. UNVERIFIED means some required native/platform/runtime proof is missing even when its automated layers passed. PASS for negative capabilities below is explicitly scoped to the current source/architecture review, not a universal runtime experiment. No test in the initial automated gate failed. The later Linux package-build failure is recorded in the convergence execution below. + +| Entry | Result | Supporting task/result | +|---|---|---| +| FR-001 | UNVERIFIED | T007–T008/T014–T015: [store/parser proof](us2.md), [watcher/sidecar proof](us4.md); native file/UI journey absent. | +| FR-002 | UNVERIFIED | T008: [Complete/Delete/Clear layers](us2.md) passed; native card-to-file flow absent. | +| FR-003 | UNVERIFIED | T009–T010: [Timer/chip/rule proof](us2.md) passed; native sharing/restart/expiry absent. | +| FR-004 | UNVERIFIED | T005–T006: [render/movement proof](us1.md) passed; native count, drag/toss/Gather/click-through absent. | +| FR-005 | UNVERIFIED | T008/T016/T018: [card](us2.md), [Agent selection](us5.md) tests passed; native selection/closure absent. | +| FR-006 | UNVERIFIED | T011–T013: [tray routes and Limits](us3.md); no actual tray/dialog/color check. | +| FR-007 | UNVERIFIED | T011/T013/T016/T018: [Limits](us3.md) and [Agent boundary](us5.md); live crossing/Agent comparison absent. | +| FR-008 | UNVERIFIED | T012/T015: [Settings workflow](us3.md), [restart distinction](us4.md); native windows/restart absent. | +| FR-009 | UNVERIFIED | T005–T006/T011: [geometry/defaults](us1.md); actual multi-display behavior absent. | +| FR-010 | UNVERIFIED | T016–T018: [Agent source/fixtures](us5.md) passed; native visibility/plugin-retention journey absent. | +| FR-011 | UNVERIFIED | T016–T018: [plugin/socket/journal proof](us5.md) passed; actual Agent Hooks window/live installation/delivery absent. | +| FR-012 | UNVERIFIED | T020: bounded source/IPC review passed; packaged network observation absent. | +| FR-013 | OBSERVATION | T014/T019: positional drift, [US4](us4.md), follow-on 004/056. | +| FR-014 | OBSERVATION | T016/T019: arrival-order/refetch drift, [US5](us5.md), follow-ons 005/059 and 061. | +| FR-015 | OBSERVATION | T016/T019: retained legacy entries/current stable plugin client, [US5](us5.md), follow-on 007/062. | +| FR-016 | UNVERIFIED | T020/T029: fresh macOS and Windows x64/ARM64 packages passed; Linux package attempt failed at dependency linking under emulation. Native platform acceptance remains open; see the convergence execution below. | +| FR-017 | UNVERIFIED | T006/T020: [native attention scenario](us1.md) not performed. | +| FR-018 | PASS (source scope) | T020: no sync, multi-user, or external work-import capability found. | +| FR-019 | PASS (source scope) | T010/T018/T020: IPC/writer ownership reviewed; no network API, slash command, or integration work writer found. | +| FR-020 | PASS (source scope) | T010/T018/T020: expiry changes timer state; no automatic work completion/merge or Harness notification writer found. | +| FR-021 | UNVERIFIED | T005–T006/T011–T012: primary-only/no-Wrangle source confirmed; native Gather absent. | +| FR-022 | PASS (source scope) | T005/T016/T020: Pig-only Species and Claude-only Harness confirmed. | +| SC-001 | UNVERIFIED | T006: [native glance usefulness](us1.md) not observed. | +| SC-002 | UNVERIFIED | T008–T010: [automated layers](us2.md) passed; actual card-to-file journey absent. | +| SC-003 | UNVERIFIED | T015: [watcher test](us4.md) passed; save-to-visible-card timing not measured. | +| SC-004 | UNVERIFIED | T013/T018: [Limit rules](us3.md) passed; native notification/tray/Agent comparison absent. | +| SC-005 | UNVERIFIED | T017–T018: [controlled Agent proof](us5.md) passed; actual native visibility/non-editability journey absent. | +| SC-006 | UNVERIFIED | T020: no packaged-process network observation. | + +No unmapped entries. Four source-scoped PASS entries, three observations, and 21 entries with remaining proof gaps; all six success criteria remain UNVERIFIED end-to-end. Source/runtime discrepancies are linked to existing follow-on issues above. Unavailable observations are a manual validation backlog in [quickstart](../quickstart.md), not newly demonstrated product defects. + +## Completion limits + +All 22 execution steps can be recorded as assessed under this task list's evidence semantics; checked boxes do not mean every product criterion passed. This pass changes only evidence documents and task progress. The specification remains Draft; Accepted ADRs remain authoritative. Product acceptance, independent review, CI on a documentation PR, and merge are not claimed. + +## Final verification (T022) + +**PASS** — evidence links/anchors, all 28 exact requirement-index rows, task IDs/labels, task/result consistency, whitespace, and preservation checks completed. `rtk git diff --check` exited 0. Only the existing tasks file changed during execution; all other 22 pre-existing edited/untracked files, including the clarified specification and plan artifacts, retained their starting hashes. Six evidence notes were added. Runtime source, lockfiles, configuration, and generated contracts remained unchanged. + +All 22 task evidence steps are recorded. The final Constitution I–VI check retains the controls in the table above: local synthetic data only, independent domains, unchanged typed boundaries, no integration install, current-main automated proof, explicit native gaps, and unchanged Draft/Accepted authority. No exception or product conformance waiver is granted. Four negative-capability entries passed within source-review scope; three limitations remain observations; 21 entries, including all six SCs, retain required proof gaps. + +The clean temporary worktree, build output, and synthetic data/configuration directories were removed after recording results; no branch was created. No review, PR, CI run, merge, or release was triggered. The complete runtime gate was not repeated after evidence-only edits. Next validation is the native/platform/process work explicitly marked UNVERIFIED in this record and the story notes. + + +## Convergence execution — 2026-10-17 (T023–T029) + +This follow-up supersedes the initial capability assessment where explicitly stated below. Runtime source is still `a48525d9a89555bf9bc925a20d626c0dc634b4ce`, verified against remote main before these builds. A fresh detached checkout, synthetic Ranch data, and empty Claude configuration were used. No runtime source, dependency, lockfile, generated contract, or acceptance requirement was changed. The still-current T004 gate was reused. + +### macOS package and partial native evidence (T023, T027) + +**PASS — package build:** `rtk task build`, exit 0, 124.86 seconds, macOS 26.6.2 arm64. Produced `Adhd Ranch.app` and `Adhd Ranch_0.0.0_aarch64.dmg` from the assessed commit. DMG SHA-256: `1407f73ecad6c64c447a35c2bb6c76f32b07427779076a94cf0791f553894800` (4,186,303 bytes). This establishes bundling, not installer execution or full native acceptance. + +**Observed native subset:** the packaged app launched with the isolated environment. Its first-launch Welcome Focus appeared as a Pig over a controlled synthetic TextEdit document. The tray exposed Focus deletion, and the native confirmation dialog appeared. Confirming deletion removed that Focus's canonical Markdown; the seed marker remained. Quit through the app's menu ended the packaged process. Restart/non-reappearance and the remaining V3 actions have not been verified. Coordinate-based cancellation attempts did not establish successful cancellation and are excluded from passing evidence. + +CLI Accessibility automation was usable even though the browser tool exposes no native control. During capture, macOS displayed an additional Codex screen/audio capture permission dialog. Validation paused without approving that permission automatically; user approval was requested. Existing captures/raw logs remain outside the repository and contain only controlled validation content intended for this pass. No further capture or dependent native scenario was attempted while approval was pending. + +**T023 remains UNVERIFIED/open.** See [US1 follow-up](us1.md#convergence-follow-up-t023). **T027 remains UNVERIFIED/open:** a matching package exists, but process-scoped network observation while exercising core scenarios has not been performed. No native FR or SC is promoted by this partial result. T024–T026 and T028 also remain open; a native launch alone does not prove their journeys. No Claude plugin was installed, credential borrowed, or personal transcript read. + +### Windows packages (T029, Windows portion) + +**PASS:** manually dispatched the existing non-publishing workflow with `rtk gh workflow run windows.yml --repo killallgit/adhd-ranch --ref main`. [Run 39070782884](https://github.com/killallgit/adhd-ranch/actions/runs/39070782884) completed successfully with head SHA matching the assessed runtime commit. Both Windows x64 NSIS and Windows ARM64 NSIS jobs passed. The workflow's unchanged build commands produced these downloaded installers: + +| Target | Installer | Bytes | SHA-256 | +|---|---|---|---| +| x86_64-pc-windows-msvc | `Adhd Ranch_0.0.0_x64-setup.exe` | 2,844,689 | `f33663980596696fee11d79a26c3593bdee95c99dc14ae94f69958b2404a6070` | +| aarch64-pc-windows-msvc | `Adhd Ranch_0.0.0_arm64-setup.exe` | 2,577,237 | `505b2f69e8f50b5f2a333a03f2a15ac75177fe16bdbff86b43a4a2003ddb9461` | + +The run's artifact retention is one day; binaries are not committed. These are fresh package-build results, not native Windows behavior or supported Windows hook delivery. No release workflow or publishing action was triggered. + +### Linux packages (T029, Linux portion) + +A disposable Ubuntu 22.04 amd64 container is running on the available arm64 Docker host with emulation. It uses the existing release matrix's system prerequisites and `npm run tauri -- build --bundles appimage,deb`, with `APPIMAGE_EXTRACT_AND_RUN=1`. Rust 1.99.0 and Node 24.21.0 match the macOS validation toolchain. Source was transferred as a Git archive of the exact assessed commit. + +The first attempt stopped before compilation: the Docker VM could not see the host bind-mounted source directory, leaving the container workspace empty; `npm ci` exited 1 because no lockfile was present. This was a validation setup failure, not a demonstrated product/lockfile defect. Transferring the archive with `docker cp` corrected the setup; locked dependency installation then succeeded. **FAILED — package attempt:** the corrected run exited 1 after 893.72 seconds. Frontend production bundling succeeded. Rust compilation stopped while linking the `tauri-plugin-fs v2.5.1` dependency build script: + +```text +error: linking with `cc` failed: signal: 11 (SIGSEGV) (core dumped) +error: could not compile `tauri-plugin-fs` (build script) due to 1 previous error +``` + +The failed invocation used Rust's bundled LLD linker (`-fuse-ld=lld`). The failure is localized to a toolchain process crash in the emulated environment; emulation/toolchain causation is suspected but not proven. It is not a demonstrated application source defect. No workaround, linker override, dependency edit, or relaxed gate was introduced. There is no successful `.deb` or AppImage artifact from this attempt. Execution stopped at this failure, as required by the implementation workflow. + +**T029 remains unchecked.** Its Windows portion passed, but Linux package compatibility remains unverified. The next proof needs a successful matching package build in a suitable Linux x64 environment, or a separately diagnosed correction to this disposable environment. Windows native behavior and Windows hook delivery are not established by the passing installers. + + +### Convergence checkpoint + +T023–T029 remain unchecked: no task's complete acceptance proof was obtained. All six SCs remain unverified end to end. Fresh macOS and Windows package results and the partial seeded-Focus native observation are retained without promoting the remaining FR/SC claims. The failed Linux attempt remains visible. Further native visual work requires the pending macOS capture-permission decision; live Agent proof also requires an independently usable disposable Claude configuration. + +Evidence-only verification: relative links and task markers checked; 22 earlier assessment tasks checked and all seven convergence tasks open. All 27 other files snapshotted at this attempt's start retained their hashes. Runtime source, manifests, lockfiles, and generated contracts remain unchanged; Linux manifests/lockfiles also matched the assessed source after dependency installation. The existing T004 gate was not repeated. No `.specify/extensions.yml` exists, so no post-implementation extension hooks apply. No new test, product fix, pipeline, PR, merge, or release was created. + +Cleanup completed: removed the owned Linux container, clean detached validation worktree, and macOS compile cache. Retained the macOS app/DMG, Windows installers, synthetic fixture, exact source archive, and raw build logs outside the repository. The Ranch process and synthetic underlay window are closed. `rtk git diff --check` exited 0; evidence links and anchors passed validation. + + +## Owner direction — ship before later native testing (2026-10-17) + +The owner explicitly authorized continuing through PR, independent review, merge, and release, with manual testing deferred until afterward. This changes execution order, not the acceptance results above. T023–T028 remain open for native/live verification, and T029 remains open until matching Windows and Linux packages succeed. The failed emulated Linux attempt remains historical evidence; the existing release workflow will supply a fresh native Linux x64 build without introducing a new pipeline. + +003 describes the existing product and adds no runtime implementation. Its known limitations remain observations with separately scoped follow-ons; this release does not implement the Draft 004–008 proposals or claim full 003 acceptance. The specification remains Draft. The shipping change contains only 003 planning/evidence documents and the release changelog; all unrelated dirty files are preserved outside its isolated branch. + +Constitution I–IV and VI retain the prior controls: unchanged local-data and integration contracts, independent domains, generated boundaries, explicit installation, and unchanged authority. For V, documentation delivery will require independent review, a green automated gate/PR CI, and merge. The owner has deferred product-level native acceptance; those criteria remain unverified rather than waived or marked complete. Release packaging must still succeed on every configured target before the existing workflow publishes. diff --git a/specs/003-ranch-today/validation/us1.md b/specs/003-ranch-today/validation/us1.md new file mode 100644 index 0000000..61f9873 --- /dev/null +++ b/specs/003-ranch-today/validation/us1.md @@ -0,0 +1,21 @@ +# US1 — Ambient Focus Animals + +Runtime commit and fresh gate: [pass record](pass-record.md#automated-gate-t004). All automated results below come from the single successful `rtk task check` run (exit 0); no additional suite was run. + +| Task | Evidence result | Acceptance limit | +|---|---|---| +| T005 | PASS — source and existing automated contracts reviewed | Does not establish native usability | +| T006 | UNVERIFIED — V3 assessed; native control unavailable | SC-001 and native overlay/display behavior remain open | + +[Focus projection](../../../crates/commands/src/focus_animals.rs) creates one Animal from each Focus, uses its title as label, emits Pig, and derives size/Motion from the Focus Timer only. [Scene composition](../../../crates/commands/src/render_scene.rs) combines independent projections into the flat contract. Species is Pig; Motion Walking/Resting; size fixed/linear; `regionId` optional. [AnimalSprite](../../../src/components/AnimalSprite.tsx) and [movement](../../../src/lib/animalMovement.ts) consume renderer vocabulary, not Focus/Task/Timer/Agent types. + +Fresh existing proof includes `projects_source_identity_label_species_and_whole_display`, `projects_running_and_expired_timer_curves_and_motion`, `task_timers_do_not_affect_focus_animals`, and [exact wire serialization](../../../crates/commands/tests/render_scene_contract.rs). [App](../../../src/components/App.test.tsx), [movement](../../../src/lib/animalMovement.test.ts), and [movement-hook](../../../src/hooks/useAnimalMovement.test.ts) suites passed with mixed scenes, selection/hit rectangles, drag/toss, region confinement, and Gather mechanics. + +V3 native items not performed: naming two actual on-screen Focuses from labels, visible Pig count, drag/toss/Gather to primary, primary-only startup and enabling another display, gap traversal, OS click-through, and attention behavior while working elsewhere. Component/geometry tests are separate evidence, not substitutes. No baseline acceptance claim is made for these items. + + +## Convergence follow-up (T023) + +On 2026-10-17, the macOS arm64 package from the same runtime commit built successfully and launched with fresh synthetic Ranch/Claude roots. The first-launch Welcome Focus was visible as a Pig. A native deletion confirmation appeared; accepting it removed the seeded Focus Markdown while retaining the seed marker. Quit through the app menu ended the process. Cancellation is not verified: earlier coordinate attempts did not establish that Cancel was activated. + +This is partial native evidence only. A subsequent macOS Codex capture-permission dialog paused visual validation pending user approval. Seed non-reappearance after restart, two named Focus labels/count, drag/toss/Gather, enabled-display confinement, OS click-through, and sustained ambient attention remain unverified. T023 remains unchecked, and SC-001/FR-004/FR-009/FR-017/FR-021 remain open. Package identity and the permission limitation are recorded in the [follow-up pass record](pass-record.md#macos-package-and-partial-native-evidence-t023-t027). diff --git a/specs/003-ranch-today/validation/us2.md b/specs/003-ranch-today/validation/us2.md new file mode 100644 index 0000000..3693f9e --- /dev/null +++ b/specs/003-ranch-today/validation/us2.md @@ -0,0 +1,18 @@ +# US2 — Focus Card, Tasks, and Timers + +Runtime commit and fresh gate: [pass record](pass-record.md#automated-gate-t004). Automated proof is the existing successful `rtk task check` run, exit 0. + +| Task | Evidence result | Native acceptance | +|---|---|---| +| T007 | PASS — source/model/coverage review | No native action claimed | +| T008 | UNVERIFIED native V1 card/CRUD; automated layers PASS | Actual card-to-file journey and closure remain open | +| T009 | UNVERIFIED native picker/restart journey; automated layers PASS | Shared-window chips and running Timer preservation need native observation | +| T010 | UNVERIFIED native expiry/revival journey; automated rules PASS | Visible ghosting/away/resting, real notifications, and tray appearance remain open | + +[Focus model](../../../crates/domain/src/focus.rs) rejects blank Task text and permits optional Timers. [Parser](../../../crates/domain/src/parse.rs) requires frontmatter `id`/`title`, reads nonempty checkboxes, and derives `focus_id:index`; that identity remains an observation, not a preservation rule. [Focus workflows](../../../crates/commands/src/focus.rs) route explicit mutations; append invokes Focus revival. [Timer workflows](../../../crates/commands/src/timers.rs) address exactly one `TimerOwner`, start/restart Running, Clear the Timer only, and expire with timer-only persistence plus settings-gated notifications. + +Fresh [store tests](../../../crates/storage/src/focus_store.rs) cover append, indexed Delete, Complete/undo, text edits preserving completion, rename, missing/corrupt sidecars, and atomic persistence paths. Command tests cover duplicate and invalid input. Existing Timer tests `start_writes_a_running_timer_for_the_preset_duration`, `start_takes_the_same_path_for_a_task`, `clear_removes_the_timer`, `revive_clears_an_expired_focus_timer`, `expire_due_persists_expired_status_for_a_task`, and notification dedup/gating passed. Task Timers do not drive Focus projection. + +[Settings normalization](../../../crates/domain/src/settings.rs) preserves positive unique custom minutes excluding built-ins 10/30/60. [Picker helper](../../../src/lib/timerPreset.ts) defines the current menu. [Settings workflow](../../../src-tauri/src/app/settings_workflow.rs) edits saved chips separately, preserves them against stale Preferences writes, persists before applying, and never clears work Timers merely because a chip was removed. Existing stale-save/normalization tests and [picker](../../../src/components/TimerPresetPicker.test.tsx)/[detail](../../../src/components/AnimalDetail.test.tsx) suites passed. + +SC-002 remains UNVERIFIED end-to-end: no native rename/duplicate/delete, Task editing, sidecar comparison after UI actions, outside-click/Escape, chip sharing across actual windows/restart, or timed native expiry was performed. Automated callback/storage/rule proof must not be reported as that journey. diff --git a/specs/003-ranch-today/validation/us3.md b/specs/003-ranch-today/validation/us3.md new file mode 100644 index 0000000..b7a2bbb --- /dev/null +++ b/specs/003-ranch-today/validation/us3.md @@ -0,0 +1,17 @@ +# US3 — Tray, Settings, and Limits + +Fresh automated gate and runtime commit: [pass record](pass-record.md#automated-gate-t004), `rtk task check`, exit 0. + +| Task | Result | Limit | +|---|---|---| +| T011 | PASS — source/defaults/coverage reviewed | Source facts separated from native observations | +| T012 | UNVERIFIED — native V4 tray/Settings journey | No tray action or OS dialog was operated | +| T013 | Automated transition/gating rules PASS; native crossings UNVERIFIED | Real red icon, notifications, and UI-to-file writes remain open | + +[Defaults](../../../crates/domain/src/settings.rs) are 5 Focuses / 7 Tasks, primary display only, confirmation on, Agents off. [Limit rules](../../../crates/domain/src/caps.rs) use Focus count and all stored Tasks, including completed Tasks; Agent Sessions are absent from the evaluator input. [Command evaluator](../../../crates/commands/src/caps.rs) emits only enabled transition notifications. Existing create/append workflows save independently of Limit state. + +[Tray source](../../../src-tauri/src/app/tray.rs) routes New Focus, Gather to overlay-0, Agents, Settings, delete, and quit; deletion returns without mutation on cancellation, and over-Limit state selects a red icon. [Settings workflow](../../../src-tauri/src/app/settings_workflow.rs) persists before updating runtime consumers and rebuilding the tray. This is current source evidence, not a native interaction result. + +Fresh tests include `focuses_to_over_calls_notifier_once`, `focuses_source_disabled_suppresses_focus_calls_but_not_task_calls`, `tasks_source_disabled_suppresses_task_calls_but_not_focus_calls`, `notification_source_toggle_is_read_from_latest_settings`, `displays_default_is_primary_only`, and Settings persistence/concurrency tests. These support thresholds, transition deduplication, notification source settings, and runtime update paths. + +V4 remains UNVERIFIED for actual tray actions, confirmation/cancellation, Preferences menu naming, Settings applying in live windows, restart persistence, saved over-threshold UI writes, visible red tray state, and real notification delivery/suppression. Completed-Task counting is a verified source observation. [US5](us5.md) separately records Agent separation and its unavailable live proof; SC-004 is not fully verified. diff --git a/specs/003-ranch-today/validation/us4.md b/specs/003-ranch-today/validation/us4.md new file mode 100644 index 0000000..e264273 --- /dev/null +++ b/specs/003-ranch-today/validation/us4.md @@ -0,0 +1,16 @@ +# US4 — Hand-Edited Markdown + +Fresh automated gate and runtime commit: [pass record](pass-record.md#automated-gate-t004), `rtk task check`, exit 0. + +| Task | Result | Limit | +|---|---|---| +| T014 | PASS — parser, storage, watcher, paths and tests reviewed | Positional identity recorded as observation | +| T015 | Automated adapter/storage checks PASS; native V1/V2 UNVERIFIED | No save-to-visible-card timing or restart journey measured | + +[Parser](../../../crates/domain/src/parse.rs) requires frontmatter id/title, ignores empty checkbox text, maps checked state, and derives `focus_id:index`. [Store](../../../crates/storage/src/focus_store.rs) handles optional sidecars: corrupt/missing Focus Timer loads as absent; missing/malformed Task Timer JSON yields no timers. Task Timers remain indexed by checkbox position. App-side indexed deletion shifts that slot; arbitrary external reorder/insert has no stable identity repair (FR-013). + +[Watcher](../../../crates/storage/src/watcher.rs) recursively observes Focus files; [host composition](../../../src-tauri/src/app/mod.rs) uses a 200 ms debounce and emits invalidations. That value is not SC-003's full editor-save-to-UI latency. Settings are loaded through the startup/settings paths, separate from the Focus-directory watcher. [Paths](../../../src-tauri/src/app/paths.rs) uses the explicit Ranch override, otherwise Unix home or Windows data-directory fallback. + +Fresh existing proof includes `fires_callback_when_a_file_changes_under_root`, `reading_a_timer_without_a_sidecar_is_none`, `reading_a_corrupt_timer_sidecar_is_none`, positional/deletion Task Timer tests, and Markdown parsing/editing/storage tests. [Seed tests](../../../src-tauri/src/app/seed.rs) `creates_example_focus_once_when_store_is_empty` and `does_not_recreate_example_after_user_clears_all_focuses` passed under T004; they are automated proof, not a first-launch native observation. + +V2 not performed: external checkbox add/Complete reflected in an actual card, approximately one-second measured visibility, work/Timer/Settings durability across native restart, Settings hand-edit applying on next launch. V1 optional-sidecar failures are verified in temporary test fixtures, but not in a running native app. SC-003 therefore remains UNVERIFIED. No schema, stable Task identity, reorder repair, or migration was added. diff --git a/specs/003-ranch-today/validation/us5.md b/specs/003-ranch-today/validation/us5.md new file mode 100644 index 0000000..f52cc46 --- /dev/null +++ b/specs/003-ranch-today/validation/us5.md @@ -0,0 +1,19 @@ +# US5 — Agent Observation and Diagnostics + +Fresh gate and runtime commit: [pass record](pass-record.md#automated-gate-t004), `rtk task check`, exit 0. Controlled integration fixtures are distinct from real Claude delivery. + +| Task | Result | Limit | +|---|---|---| +| T016 | PASS — source and existing controlled tests reviewed | No real-session census or plugin installation | +| T017 | Automated install-dialog/default-off behavior PASS; native UI UNVERIFIED | No actual toggle/dialog action operated | +| T018 | UNVERIFIED — optional live/native check unavailable | Agent Hooks window, live delivery, Limit/file independence and toggle journey remain open | + +[Agent Session](../../../crates/domain/src/session/agent_session.rs) has identity/name/Pen/activity, no Focus/Task/Timer fields; activity is Working/Idle. [Hook types](../../../crates/domain/src/agents/hooks.rs) define Start/Working/Idle/End and optional session/pen diagnostic fields. [LiveSessions](../../../crates/storage/src/agent_session_store.rs) is an in-memory arrival-order fold; unknown sessions can become visible on a later establishing/updating Firing, with no startup census. [Journal](../../../crates/storage/src/agent_hooks/journal.rs) retains unchanged Firings without retaining raw prompt payloads. + +[Plugin owner](../../../src-tauri/src/app/claude_plugin.rs) validates configuration and gates installation to the Install Hooks window. [Stable client placement](../../../src-tauri/src/app/claude_hook.rs) atomically replaces a local client and preserves the prior binary on failure. Disabling via [Settings effects](../../../src-tauri/src/app/settings_workflow.rs) clears local sessions, not the installed plugin. [Host hook adapter](../../../src-tauri/src/app/agent_hooks.rs) ignores Firings while disabled. No personal configuration or live CLI installation was touched. + +Fresh plugin tests verify complete matching user-scope identity, idempotent installation, update/repair/reinstall paths, and preservation on invalid marketplace sources. Stable-client tests cover replacement/failure isolation. [Socket integration](../../../crates/storage/tests/agent_hook_socket.rs) passed real temporary-socket/client/wrapper delivery and silent success with Ranch absent. The client/server use bounded payload/read/write policies. [App tests](../../../src/components/App.test.tsx) passed non-editable Agent selection and independent Focus/Agent changes; [Limit source](../../../crates/domain/src/caps.rs) cannot count Agent Sessions. + +[Agent Hooks view source](../../../src/components/AgentDebugWindow.tsx) renders wiring/configuration health, live sessions, recent Firings, and “no change” rows; loading/error states are distinct from empty lists. This source review does not prove that an actual native window displayed those results. + +T018's live check was not attempted: native control is disabled, and no independently usable disposable authenticated Claude environment was provisioned. No credentials were borrowed to make it run. Native checks explicitly UNVERIFIED: opening Agent Hooks and inspecting all three sections/unchanged repeat, actual Install Hooks/repair, an observed post-listener session, no Focus card on click, before/after work-file/Limit comparison, and toggle-off retaining Focus Animals/plugin. SC-004's live Agent portion and SC-005 remain open. Windows hook delivery is unsupported, not a failing Unix check. From 889f8a005d9c46ca297dee2301b1ad0465cd0688 Mon Sep 17 00:00:00 2001 From: archae0pteryx Date: Sat, 17 Oct 2026 15:06:53 -0700 Subject: [PATCH 2/2] docs: distinguish Linux package target from build proof --- specs/003-ranch-today/contracts/current-behavior.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/003-ranch-today/contracts/current-behavior.md b/specs/003-ranch-today/contracts/current-behavior.md index ad945c1..05c12d3 100644 --- a/specs/003-ranch-today/contracts/current-behavior.md +++ b/specs/003-ranch-today/contracts/current-behavior.md @@ -25,7 +25,7 @@ V1–V7 refer to [quickstart](../quickstart.md). FR-013–FR-015 require accurat | 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; Linux/Windows packages build; no Windows hook delivery. | [Windows workflow](../../../.github/workflows/windows.yml), [release matrix](../../../.github/workflows/release.yml); platform gates. | +| 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. |