# Phase 24.1 — Discussion Log

**Date:** 2026-05-20
**Mode:** discuss (default)

---

## Pre-Selected Carry-Forwards

From prior phases, no re-asked:

- **Machine identity** = OS hostname (Phase 23 D-03, reaffirmed in Phase 24
  Deferred Ideas which explicitly punts UUID / gh-account-email alternatives
  to Phase 35).
- **Git CLI shell-out** (Phase 24 D-01).
- **Write trigger** piggybacks on Phase 24 D-13 commune/signoff commit path
  (no separate write trigger needed — ROADMAP SC7 literal).

---

## Gray Areas Presented

User selected ALL FOUR:

1. Schema shape vs perch info.json
2. Project identity key
3. last_started + last_machine semantics
4. History bounds + dedup rules

---

## Area 1 — Schema Shape vs Perch info.json

**Setup:** Perch `project_history` is currently `Vec<String>` (Phase 32
D-08); tracked schema draft needs first_seen/last_seen timestamps.
ROADMAP SC5 demands consistency.

**Options:**
- (selected) Upgrade perch to richer shape too — both sides identical
  `[{name, first_seen, last_seen}]`. Breaking change to live perches
  mitigated by Phase 32 graceful-deserialize Value round-trip pattern.
- Perch stays flat; tracked is a richer mirror.
- Mirror flat shape; timestamps recovered from `git log -p info.json`.

**Selected:** Upgrade perch to richer shape too. → Locked as **D-05**.

---

## Area 2 — Project Identity Key

**Setup:** Phase 32 `derive_current_repo_names()` returns up to 2 names
(folder basename + origin basename). ROADMAP draft adds `root` abs path.

**Options:**
- (selected) Name string only — matches Phase 32 D-03 verbatim. Both
  names appended as separate entries when they differ. No `root`, no
  remote URL.
- Name + root (schema draft literal).
- Asymmetric perch/tracked (rejected as violating just-locked D-05).
- Name + git remote URL.

**Selected:** Name string only. → Locked as **D-02 (carried)**.
ROADMAP draft `root` field dropped.

---

## Area 3 — last_started + last_machine Semantics

### Q3a: `last_started` trigger

**Setup:** Phase 24 D-11 defines 4 triggers (boot|pulse|commune|signoff).

**Options:**
- (selected) `boot` trigger only — pairs with sessions log SC7. Pulses
  don't count.
- Every wake (boot + pulse).
- boot + every commune/signoff.

**Selected:** boot only. → Locked as **D-06**.

### Q3b: `last_machine_name` trigger

**Options:**
- (selected) Every tracked write (commune/signoff/boot) — matches Phase
  23 Stamp's Machine trailer cadence.
- Only on boot.

**Selected:** Every tracked write. → Locked as **D-07** + machine_history
bump rule **D-08**.

---

## Area 4 — Bounds + Migration

### Q4a: History bounds

**Options:**
- (selected) Unbounded, insertion order (matches Phase 32 D-08).
- Unbounded, most-recently-seen first (LRU order).
- LRU cap (max 50).

**Selected:** Unbounded, insertion order. → Locked as **D-11**.

### Q4b: Migration synth

**Options:**
- (selected) All legacy entries get first_seen = last_seen = perch
  info.json mtime. Conservative — no fabricated history.
- first_seen = perch dir ctime, last_seen = info.json mtime.
- Per-entry synthesize via `git log -p` scan.

**Selected:** mtime-only fallback. → Locked as **D-13**.

---

## Deferred Ideas

- LRU cap on history (revisit on real growth)
- Richer project identity (root path, remote URL) — Phase 35
- Per-machine UUID alternative — Phase 35
- Cross-machine concurrent write conflict — Phase 35
- psyche-download payload embedding — Phase 25
- Sessions log ↔ info.json consistency check in doctor

---

## Addendum — Post-Lock Amendment (same session)

**User direction:** "update to also include `branch` for each entry.
dedup still matches solely on project name"

- project_history element shape gains `branch: String` field. New
  shape = `{name, branch, first_seen, last_seen}`. machine_history
  shape unchanged.
- Dedup key remains `name` only. `branch` is single-value, overwritten
  on every bump (parallels `last_seen` semantics).
- Capture path: `git -C {cwd} rev-parse --abbrev-ref HEAD` at write
  time. Empty string `""` on failure / detached HEAD / no-git
  (Phase 24 D-02 fallback).
- Existing Phase 32 helper `append_project_history` signature gains
  `branch: &str` parameter.
- Migration synth: legacy entries get `branch: ""` (no historical
  signal); fills in on next live bump.
- Updated decisions: D-05 (shape), D-10 (bump rule + signature),
  D-13 (migration synth).

---

## Claude's Discretion

- Struct names (`HistoryEntry`, `TrackedAgentInfo`)
- Whether a shared `append_history_entry()` primitive serves both
  perch + tracked
- Doctor sub-line visual formatting
- `last_project_name` Rust type (`Option<String>` recommended)
- Test coverage breakdown