# Phase 32: List Overhaul + Skill Hint Audit - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-16
**Phase:** 32-list-overhaul-skill-hint-audit
**Areas discussed:** --here cwd-match semantics, Flag conflict + hint scope, HINT-03 specific values, Refactor scope + plan split

---

## --here cwd-match semantics

### Sub-Q1: Match algorithm

| Option | Description | Selected |
|--------|-------------|----------|
| Canonicalize both, == | std::fs::canonicalize on both sides, exact PathBuf equality. Matches build_resolve_spec pattern. | ✓ (then superseded) |
| Raw string equality | Fastest, brittle on Windows. | |
| Path-prefix match | Useful for monorepos, blurs --here semantics. | |

**User's choice:** Canonicalize both, == — BUT then redirected the entire semantics: --here should compare against a new `project_history` array of repo NAMES on info.json, not against `cwd` paths. cwd represents momentary working dir; project_history captures durable "has been active here" relationship.

### Sub-Q2: Legacy info.json without cwd field

| Option | Description | Selected |
|--------|-------------|----------|
| Treat as match (include) | Mirrors Phase 31 D-09. | |
| Treat as no-match (exclude) | Strict cwd record requirement. | |
| Treat as match + stderr note | Include but warn. | |

**User's choice:** Reshape the design — add new `project_history: Vec<String>` field to info.json storing repository NAMES only (e.g. `claude_skill_owl`, `rebno`, `wit-what`). Legacy perches get empty default; populated on next start/listen.

### Sub-Q3: Helper name

| Option | Description | Selected |
|--------|-------------|----------|
| is_perch_in_current_repo | LIST-07 exact wording. | |
| perch_cwd_matches_current | Literal cwd-comparison name. | |
| is_perch_here | Mirrors flag name. | |

**User's choice:** `perch_has_repo_history` — takes a repo name (not a working dir path). Replaces LIST-07's literal name.

### Sub-Q4: Repo-name derivation source

| Option | Description | Selected |
|--------|-------------|----------|
| git rev-parse --show-toplevel basename | Shell out to git, basename. | |
| Basename of cwd, no git check | Path::new(cwd).file_name(). | |
| Walk for .git, basename | In-process, no git binary. | |

**User's choice:** Check BOTH basename of the dir containing .git AND remote origin basename (via `git` or `gh` CLI). Both stored in project_history because local-name and remote-name can diverge.

### Sub-Q5: project_history write trigger

| Option | Description | Selected |
|--------|-------------|----------|
| On every $LIVE start / $OWL listen | Self-maintaining at perch creation/refresh. | ✓ |
| On every poll cycle | Continuous, lock contention risk. | |
| On $LIVE start only (one-shot) | Misses cross-repo migration. | |

**User's choice:** Every $LIVE start / $OWL listen.

### Sub-Q6: No-git-repo fallback

| Option | Description | Selected |
|--------|-------------|----------|
| Hard error | --here requires git context. | |
| Silent empty result | Cleanest UX, hides config issue. | |
| Fall back to cwd-basename match | Path::new(cwd).file_name() as single name. | ✓ |

**User's choice:** Fall back to cwd-basename match.

**Notes:** This area drove the biggest design shift. REQUIREMENTS.md LIST-04 wording (which references `info.json.cwd`) must be amended in Plan 01 to reference `info.json.project_history`. ROADMAP.md Phase 32 success criterion 2 needs parallel revision.

---

## Flag conflict + hint scope

### Sub-Q1: --all and --offline mutex UX

| Option | Description | Selected |
|--------|-------------|----------|
| Clap-level conflicts_with | Standard CLI error, exit 2. | ✓ |
| Custom stderr + exit 1 | Owl-themed error. | |
| Last-wins precedence | Unix-y, silent. | |

**User's choice:** Clap-level conflicts_with.

### Sub-Q2: $LIVE list parallel discovery hint

| Option | Description | Selected |
|--------|-------------|----------|
| Yes, parallel hint | Mirrors LIST-05 for symmetry. | ✓ |
| No, $OWL-only | LIST-05 literally only says $OWL. | |
| Yes, live-specific wording | Mentions --here too. | |

**User's choice:** Yes, parallel hint.

### Sub-Q3: --here zero-result hint behavior

| Option | Description | Selected |
|--------|-------------|----------|
| Yes, hint mentions --here | "Drop --here or pass --all to widen." | ✓ |
| Yes, same as LIST-05 | Static hint. | |
| No, --here implies user wanted local-only | No hint. | |

**User's choice:** Yes, hint mentions --here.

---

## HINT-03 specific values

### Sub-Q1: /spt:commune

| Option | Description | Selected |
|--------|-------------|----------|
| Empty string | Per HINT-03 audit. | ✓ |
| Keep as <msg> | User normally types message. | |
| Optional [<msg>] | Compromise. | |

**User's choice:** Empty string. **Notes:** Commune messages are composed by the live agent, not the user. No user interactivity post-fire.

### Sub-Q2: /spt:psyche-download

| Option | Description | Selected |
|--------|-------------|----------|
| [<id>] | Bracketed optional positional. | ✓ |
| [id] | No angle brackets. | |
| <id>? | Trailing-? convention. | |

**User's choice:** [<id>].

### Sub-Q3: /spt:whoami

| Option | Description | Selected |
|--------|-------------|----------|
| Empty string "" | Matches clear-psyche/signoff. | ✓ |
| Keep (no arguments) | Explicit, verbose. | |
| -- (literal end-of-options) | Unusual, not used elsewhere. | |

**User's choice:** Empty string "".

---

## Refactor scope + plan split

### Sub-Q1: LIST-06 extraction depth

| Option | Description | Selected |
|--------|-------------|----------|
| Full extraction to src/common/list_filter.rs | Strong shared truth, easier future changes. | ✓ |
| Shared enum + helper, duplicate render | Less risky. | |
| Duplicate filter, document intent | Minimal change. | |

**User's choice:** Full extraction.

### Sub-Q2: Plan split

| Option | Description | Selected |
|--------|-------------|----------|
| Three plans (schema / list code / hint audit) | Clean dependency chain. | ✓ |
| Two plans (code vs docs) | | |
| Single plan | Lots of commits in one plan. | |

**User's choice:** Three plans.

### Sub-Q3: HINT-05 regression-guard test

| Option | Description | Selected |
|--------|-------------|----------|
| Rust integration test (tests/skill_hints.rs) | Runs in cargo test, single enforcement. | ✓ |
| PowerShell script in DEPLOY.ps1 | Deploy-time gate. | |
| Both | Belt and braces. | |

**User's choice:** Rust integration test.

---

## Claude's Discretion

- Repo-name derivation exact code path (in-process .git walk vs shell-out to `git`; `gh` as last-resort fallback) — recommendation logged in CONTEXT.md.
- Plan 01 vs Plan 02 boundary for `project_history` write-site updates — recommendation: Plan 01.
- `live_dim_status` vs raw `eprint!` alignment during list_filter.rs extraction.
- Sort order within `--here` results (alphabetical vs last-active).
- `gh` CLI invocation as second-tier remote-name source.

## Deferred Ideas

- Backfill/migration for legacy perches lacking `project_history`.
- `project_history` pruning if array growth becomes a real-world issue.
- Per-repo branch tracking (`--here --branch main`).
- Cross-reference: body_addendum symmetrization (Phase 31 deferred).
- `--here` gating in `$LIVE pick-spec` post-`project_history` (Phase 33+ design).