Make Handoff::Store the only owner of handoff file I/O #1401

New issue

Closed

opened 2026-10-26 19:15:47 +00:00 by jared · 1 comment

jared commented

2026-10-26 19:15:47 +00:00

Owner

Problem

File I/O for handoff files sits in three classes. Handoff::Document reads its own file (plugins/os/lib/handoff/document.rb:13, File.binread) and writes its own file (document.rb:35, File.binwrite). Handoff::StatusCommand deletes files (status_command.rb:15, File.delete). Handoff::Store already exists, but it only reads (Dir.glob, File.realpath). Disk access has no single owner, and Document tests must touch the disk.

Reproduce

n/a: structure change; behavior stays the same.

Approach

Make Handoff::Store the only owner of handoff file I/O: read, write, and delete (about 15 lines). Document becomes pure: it takes text and returns text. StatusCommand asks the store to delete.

Required work:

Remove the file read from Handoff::Document — check: absent File.binread in plugins/os/lib/handoff/document.rb
Remove the file write from Handoff::Document — check: absent File.binwrite in plugins/os/lib/handoff/document.rb
Remove the file delete from Handoff::StatusCommand — check: absent File.delete in plugins/os/lib/handoff/status_command.rb
Add the write path to the store — check: present File.binwrite in plugins/os/lib/handoff/store.rb

Acceptance criteria

Given the existing suite, when it runs after the change, then it passes with no behavior change.
Given a Handoff::Document built from a string, when its tests run, then they do not touch the disk.

Owner sketch

class Handoff::Store
  def read(path)
  def write(document)
  def delete(document)
end

Origin

Trigger: the blind pattern-distance experiment, /home/jared/dev/cc-os/docs/system-design-format/proof/pattern-distance-experiment.md (main, commit 8991003e; handoff sections). Three strict patterns flag the same lines: Repository R1, Hexagonal R1, Layers R2.
Improvised this session: none
Chain: file I/O spread over Document, StatusCommand, and Store ← Store was built for reads only ← DESIGN (source: plugins/os/lib/handoff/store.rb)
Root candidate: none found; searched Handoff::Store, handoff/store, Handoff::Document, StatusCommand, plugins/os/lib/handoff, file I/O
Where: plugins/os/lib/handoff/document.rb, plugins/os/lib/handoff/status_command.rb, plugins/os/lib/handoff/store.rb
Session: 4e988e4b-0efd-4090-9e80-c4ccd99e73b6
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os--claude-worktrees-fast-batch-15/4e988e4b-0efd-4090-9e80-c4ccd99e73b6.jsonl
Method note: this is the first test of the pattern-distance method. After the change, judge whether the code reads better.

VERDICT: CREATE

## Problem File I/O for handoff files sits in three classes. `Handoff::Document` reads its own file (`plugins/os/lib/handoff/document.rb:13`, `File.binread`) and writes its own file (`document.rb:35`, `File.binwrite`). `Handoff::StatusCommand` deletes files (`status_command.rb:15`, `File.delete`). `Handoff::Store` already exists, but it only reads (`Dir.glob`, `File.realpath`). Disk access has no single owner, and Document tests must touch the disk. ## Reproduce n/a: structure change; behavior stays the same. ## Approach Make `Handoff::Store` the only owner of handoff file I/O: read, write, and delete (about 15 lines). `Document` becomes pure: it takes text and returns text. `StatusCommand` asks the store to delete. Required work: 1. Remove the file read from `Handoff::Document` — check: absent `File.binread` in `plugins/os/lib/handoff/document.rb` 2. Remove the file write from `Handoff::Document` — check: absent `File.binwrite` in `plugins/os/lib/handoff/document.rb` 3. Remove the file delete from `Handoff::StatusCommand` — check: absent `File.delete` in `plugins/os/lib/handoff/status_command.rb` 4. Add the write path to the store — check: present `File.binwrite` in `plugins/os/lib/handoff/store.rb` ## Acceptance criteria 1. Given the existing suite, when it runs after the change, then it passes with no behavior change. 2. Given a `Handoff::Document` built from a string, when its tests run, then they do not touch the disk. ## Owner sketch ```ruby class Handoff::Store def read(path) def write(document) def delete(document) end ``` ## Origin - Trigger: the blind pattern-distance experiment, /home/jared/dev/cc-os/docs/system-design-format/proof/pattern-distance-experiment.md (main, commit 8991003e; handoff sections). Three strict patterns flag the same lines: Repository R1, Hexagonal R1, Layers R2. - Improvised this session: none - Chain: file I/O spread over Document, StatusCommand, and Store ← Store was built for reads only ← DESIGN (source: plugins/os/lib/handoff/store.rb) - Root candidate: none found; searched Handoff::Store, handoff/store, Handoff::Document, StatusCommand, plugins/os/lib/handoff, file I/O - Where: plugins/os/lib/handoff/document.rb, plugins/os/lib/handoff/status_command.rb, plugins/os/lib/handoff/store.rb - Session: 4e988e4b-0efd-4090-9e80-c4ccd99e73b6 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os--claude-worktrees-fast-batch-15/4e988e4b-0efd-4090-9e80-c4ccd99e73b6.jsonl - Method note: this is the first test of the pattern-distance method. After the change, judge whether the code reads better. VERDICT: CREATE

jared added the

plugin/os

filed-by/user

category/structure

labels

2026-10-26 19:15:47 +00:00

jared referenced this issue from a commit

2026-10-26 20:11:56 +00:00

refactor(os): Handoff::Store owns all handoff file I/O; Document parses text only (#1401)

jared referenced this issue from a commit

2026-10-26 20:11:56 +00:00

docs(os): regenerate handoff model for Store-owned file I/O (#1401)

jared commented

2026-10-26 20:12:51 +00:00

Author

Owner

Resolution

Done: Handoff::Store is built on its handoffs directory and owns read, write, delete, complete; Document.new(path:, text:) parses text only; StatusCommand deletes through the store; Store.for_project keeps the .cc-os realpath rule and passes default_project. Ruling R1 predicted (74%), R2/R3 fix list.

Evidence: fast-batch-17 merged at main 80a39130 (commits e5695b2c, 86ca5729, 532b8f05, 428ee39a); os suite 47 runs 0 failures; grep finds no File.binread/binwrite/delete outside Store; blind judge: better, 75%.

Follow-ups: Document unit tests from strings: captured separately in this session

## Resolution **Done:** Handoff::Store is built on its handoffs directory and owns read, write, delete, complete; Document.new(path:, text:) parses text only; StatusCommand deletes through the store; Store.for_project keeps the .cc-os realpath rule and passes default_project. Ruling R1 predicted (74%), R2/R3 fix list. **Evidence:** fast-batch-17 merged at main 80a39130 (commits e5695b2c, 86ca5729, 532b8f05, 428ee39a); os suite 47 runs 0 failures; grep finds no File.binread/binwrite/delete outside Store; blind judge: better, 75%. **Follow-ups:** Document unit tests from strings: captured separately in this session

jared closed this issue

2026-10-26 20:12:51 +00:00

jared referenced this issue

2026-10-26 20:15:37 +00:00

Test Handoff::Document from strings, keep one CLI test per path #1406