Daemon convention: append a compact "#→name" Refs index when a message cites briefs/feedback by number

You are being dispatched from flower Brief #244: Daemon convention: append a compact "#→name" Refs index when a message cites briefs/feedback by number

Recall pointer:
- Use recall_brief with id 244 for the full folder if you need provenance.

Target:
- project: flower (/Users/mikeferrara/Documents/code/flower)
- branch: flower/244-refs-index
- worktree: not specified
- kind: fresh

Current brief spec:
# Daemon messaging convention: append a compact `Refs:` index for cited entities

## Problem / operator intent (Mike, 2026-07-04)
When a daemon/agent message cites briefs/feedback/decisions/sessions by NUMBER (#NNN), the reader (operator or another agent) can't decode the numbers without a lookup. Standing convention: append a compact **`Refs:`** index at the END of such messages mapping each cited number → its **canonical stored title/first-line**.

## Resolved decisions
- **Name = the REAL stored title** (operator-clarified, event 3201): resolve #→ `brief.title` / `feedback.summary` / `decision.header` / `session.title` — NOT a daemon paraphrase (avoids stale/guessed names). Truncate long titles (~60 chars + `…`). Example: `#230: Let's add an auto-dispatch toggle to the brief rows on /briefs for bri…`
- **Entity types:** all #-addressable types. Bare `#N` = brief (the common default); typed prefixes otherwise — `fb#N` feedback, `dec#N` decision, `sess#N` session, `dr#N` dispatch_request. The Refs index expands whatever was cited.
- **Scope:** append `Refs:` when a message cites ≥1 numbered entity AND is substantive (checkpoint / handoff / report / status / brief-write / operator-facing summary). Skip on terse timer-tick acks / trivial one-liners. Dedupe; first-mention only; cap ~8–10 entries (append "+N more" when over).
- **Format:** `#NNN: <title>` one per line for a list; collapse to a ` · `-joined one-liner when refs are few (≤2–3) and short. Matches the operator's example.

## Scope of work
1. **Charter convention (primary):** encode the rule in `AgentConventions` (+ per-role bodies / `DaemonCharterDefaults`) so all roles inherit it. **Sequence/fold with #170** (Phase-3 decisions charter integration) + the charter-refresh companion — they edit the SAME `AgentConventions`/`DaemonCharterDefaults` surface, so landing them together avoids version churn + repeated `PromptTemplateSeeder` re-seeds (same lesson as #155↔#170). Bump the DaemonCharterDefaults version once for the combined charter edit.
2. **Resolver helper/tool (small, recommended fast-follow):** a batch `#→canonical title` resolver (given typed refs, return `{ref: title}`) so daemons emit real titles cheaply without per-ref lookups or stale guesses. A tiny MCP tool or `RecallService` helper. Interplays with #78 (compact plain refs by default; link only on first mention).

## Relationships
- **#78** — prior entity-ref recommendation (compact plain refs; link on first mention); this operationalizes it.
- **#170** + charter-refresh companion — same charter surface; sequence together (soft coordination, not a hard dependency).

## Open (minor, non-blocking — defaults above stand unless operator objects)
- Exact truncation length + cap N.
- Resolver tool ships-with vs deferred (recommend: land the convention in the charter now; resolver as a fast-follow — daemons resolve from context/recall in the interim).

## Provenance
Operator request + clarification (Mike, 2026-07-04); created by flower-orchestrator, refined by flower-refine.

**Disposition:** `planned` — convention is clear; land the charter edit sequenced with #170's charter change set. Resolver = small fast-follow build. Orchestrator owns dispatch.

Recent/key trace events:
[1] participant_joined flower-orchestrator: (no body)
[2] note_added flower-orchestrator: Operator-requested (Mike, 2026-07-04). FOR REFINEMENT. Strategy: whenever a daemon (or agent) message cites a brief / feedback / decision / session by NUMBER (#NNN), it should append a compact `Refs:` index at the END of the message mapping each cited number → its short name/title, so the reader (operator or another agent) can decode the numbers without a lookup.

Example:
> ... merged #124 and #170; #226 is complete ...
>
> **Refs:** #124 orphaned-handoff PR-8 · #170 decision_* → charters · #226 epic-lead orchestration

## Connects to prior work
Brief #78 already recommended exactly this shape — "compact plain refs by default, emit a link only on first mention in a checkpoint/handoff or in a small `Refs:` block" (see inbox note 2). This brief operationalizes that as a standing daemon messaging convention.

## Refinement questions (why status=refining)
- **Entity types:** which #-addressable types get indexed — briefs, feedback, decisions, sessions, dispatch_requests? (Probably all, but names differ by type; may need a type prefix, e.g. `fb#127`.)
- **Scope:** every message, or only checkpoints/handoffs/reports? Terse timer-tick acks probably shouldn't carry a Refs block. Proposal: any message citing ≥1 ref, deduped, capped at ~N entries.
- **Format:** one-line `Refs: #NNN short-name · #NNN short-name` vs a bulleted list. Keep compact; first-mention only.
- **Name resolution:** the daemon usually knows the name from context, but to avoid stale/guessed names a tiny resolver helper/tool (#→canonical short name) may be worth it — interplay with #78's clickable-refs plan.
- **Home:** this is a charter convention → fold the final rule into the charter-refresh brief (companion) so all roles inherit it; the optional resolver is a small separate build.

## Refs
#78 (entity-ref recommendation / inbox note 2), and the charter-refresh brief (companion, above).
[3] note_added flower-orchestrator: OPERATOR CLARIFICATION (Mike, 2026-07-04): the "name" in the index is the entity's CANONICAL TITLE / first-line — NOT an ad-hoc paraphrase. Exact example given:

  #230: Let's add an auto-dispatch toggle to the brief rows on /briefs for bri…

i.e. the format is `#<num>: <the brief's real title>` (truncation OK when long). This directly answers the "name resolution" refinement question: resolve #→name against the REAL stored title (brief.title / feedback.summary / decision title), not the daemon's memory — so a tiny resolver helper/tool is likely worth it to avoid stale or guessed names. Layout is probably one `#NNN: <title>` per line for a short list (matches the operator's example), collapsing to a compact ` · `-joined one-liner only when refs are few/short. Supersede my earlier paraphrased example in the seed note with this title-based form.
[4] status_change flower-orchestrator: (no body)
[5] participant_joined flower-refine: (no body)
[6] plan_proposed flower-refine: # Daemon messaging convention: append a compact `Refs:` index for cited entities

## Problem / operator intent (Mike, 2026-07-04)
When a daemon/agent message cites briefs/feedback/decisions/sessions by NUMBER (#NNN), the reader (operator or another agent) can't decode the numbers without a lookup. Standing convention: append a compact **`Refs:`** index at the END of such messages mapping each cited number → its **canonical stored title/first-line**.

## Resolved decisions
- **Name = the REAL stored title** (operator-clarified, event 3201): resolve #→ `brief.title` / `feedback.summary` / `decision.header` / `session.title` — NOT a daemon paraphrase (avoids stale/guessed names). Truncate long titles (~60 chars + `…`). Example: `#230: Let's add an auto-dispatch toggle to the brief rows on /briefs for bri…`
- **Entity types:** all #-addressable types. Bare `#N` = brief (the common default); typed prefixes otherwise — `fb#N` feedback, `dec#N` decision, `sess#N` session, `dr#N` dispatch_request. The Refs index expands whatever was cited.
- **Scope:** append `Refs:` when a message cites ≥1 numbered entity AND is substantive (checkpoint / handoff / report / status / brief-write / operator-facing summary). Skip on terse timer-tick acks / trivial one-liners. Dedupe; first-mention only; cap ~8–10 entries (append "+N more" when over).
- **Format:** `#NNN: <title>` one per line for a list; collapse to a ` · `-joined one-liner when refs are few (≤2–3) and short. Matches the operator's example.

## Scope of work
1. **Charter convention (primary):** encode the rule in `AgentConventions` (+ per-role bodies / `DaemonCharterDefaults`) so all roles inherit it. **Sequence/fold with #170** (Phase-3 decisions charter integration) + the charter-refresh companion — they edit the SAME `AgentConventions`/`DaemonCharterDefaults` surface, so landing them together avoids version churn + repeated `PromptTemplateSeeder` re-seeds (same lesson as #155↔#170). Bump the DaemonCharterDefaults version once for the combined charter edit.
2. **Resolver helper/tool (small, recommended fast-follow):** a batch `#→canonical title` resolver (given typed refs, return `{ref: title}`) so daemons emit real titles cheaply without per-ref lookups or stale guesses. A tiny MCP tool or `RecallService` helper. Interplays with #78 (compact plain refs by default; link only on first mention).

## Relationships
- **#78** — prior entity-ref recommendation (compact plain refs; link on first mention); this operationalizes it.
- **#170** + charter-refresh companion — same charter surface; sequence together (soft coordination, not a hard dependency).

## Open (minor, non-blocking — defaults above stand unless operator objects)
- Exact truncation length + cap N.
- Resolver tool ships-with vs deferred (recommend: land the convention in the charter now; resolver as a fast-follow — daemons resolve from context/recall in the interim).

## Provenance
Operator request + clarification (Mike, 2026-07-04); created by flower-orchestrator, refined by flower-refine.

**Disposition:** `planned` — convention is clear; land the charter edit sequenced with #170's charter change set. Resolver = small fast-follow build. Orchestrator owns dispatch.
[7] status_change flower-refine: (no body)
[8] refinement flower-refine: **Refinement round 2 — operator input (Mike, 2026-07-04). These AMEND the spec above (supersede where noted).**

1. **Name resolution → AMBIENT, not a dedicated resolver tool (supersedes "Scope of work #2").** The daemon almost always ALREADY has the title in context, because the `recall_*` responses it's already making carry it (`recall_briefs.title`, `recall_signals.payload.brief_title`, `recall_brief`, `recall_decisions.header`, …). So instead of a separate resolver toolcall, **enrich existing `recall_*` responses to consistently carry `{title, status}` for the ids they surface** — titles ride along on calls the daemon already makes → zero extra toolcalls. A standalone resolver becomes a rare FALLBACK only (a `#` cited but not in recent context). (Live proof this session: I could produce #244/#170 titles from context but NOT #78's — exactly the cited-but-not-pulled gap the sidecar closes.)

2. **Truncate SHORT.** Operator only needs a mental nudge at the idea, not the full title — a short prefix suffices and saves tokens over the long run. Cap ~**40 chars** (was 60) + `…`, **configurable**.

3. **Include STATUS (cheap, high-signal).** Append each entity's current status: `#244: Daemon convention: append a compact… (planned)`. Free once titles are ambient (status rides the same enriched response). **Open-questions surfacing = OUT of the compact index** (too heavy; belongs in the detailed/click-through view) — status only.

4. **Cost/noise controls (the crux — must be cheap AND not noisy):**
   - **Summary/substantive messages ONLY, never ticks** (as before).
   - **Cross-message dedupe (NEW):** suppress a ref's entry if it was already shown in a recent summary message within a window — first-mention-wins ACROSS messages, not just within one — so the same title isn't repeated tick after tick.
   - **Config-tunable (config-as-data, env-overridable):** truncation length, cap N, dedupe window, include-status on/off, and optionally a cadence gate. Verbosity dials in; defaults conservative.

**Net effect:** the primary build shrinks from "convention + resolver tool" to "**convention (charter) + enrich `recall_*` responses with `{title,status}`**" — cheaper for daemons AND for tokens. Still sequence the charter edit with #170. Keeping #244 `planned`; these amendments are folded direction, not new forks.
[9] refinement flower-refine: **Refinement round 3 — operator idea (Mike, 2026-07-04): a persistent "sticky list" for active-citation refs instead of re-emitting inline.**

The instinct is good — a PERSISTENT, always-visible working-set of the citations currently in play, so they don't repeat inline every message. Worth building. But the specific vehicle floated (Claude Code's todo list) is a mismatch for THIS convention:
- **Visibility:** the CC todo list renders only in that one Claude-Code daemon's terminal chrome — not the flower web UI (/room, /briefs) where the operator actually reads, and not in Codex/Pi daemon terminals.
- **Cross-harness:** flower is cross-harness (Claude/Codex/Pi); a convention built on a Claude-Code-only affordance wouldn't generalize to the other daemon harnesses.
- **Ephemeral/agent-scoped:** todos die on reset/compaction and aren't shared or queryable — a citation working-set wants to be durable + shared.
- **Semantic:** todos are a task/progress tracker, not reference data.

**Flower-native version of the instinct (recommended):** a persistent **"active refs" rail** in the flower UI (room sidebar / a strip near the message stream / on /briefs) showing the citations currently in play — `#N <short title> (status)` — auto-updating, always visible WITHOUT inline repetition. Durable, cross-harness, and where the operator actually looks. Pairs perfectly with the cross-message dedupe (round 2): the rail holds the working-set; inline `Refs:` fires only on genuinely-new refs. Ties to #216 (room/feed redesign) + #78.

**Recommendation:** keep the inline `Refs:` charter convention (deduped) as the baseline that works in EVERY surface/harness; add the "active refs rail" as the richer UI layer. Both, not either. (The CC todo list could still be a nice *local* convenience for a Claude daemon's own working-set, but it's not the operator-facing mechanism.)
[10] note_added flower-refine: **Round-3 decision (operator, 2026-07-04):** the CC-todo-list vehicle is **DROPPED**. The persistent "active refs" rail is **ENDORSED** and spun out to its own brief **#246** (rooms-UI feature, `refining` — needs a light design pass). #244 remains the inline `Refs:` charter convention (the cross-harness baseline); #246 is the richer UI layer that carries the working-set and feeds #244's cross-message dedupe. Both, not either.

Recommended linked context:
{
    "todos": [],
    "scratchpads": []
}

Execution notes:
- Treat the brief as the source of truth.
- Keep work scoped to this dispatch request.
- Use brief_append / brief_update_status when reporting material progress; as your final dispatched-worker step, call brief_dispatch_complete with dispatch_request_id (or brief_id) and actor_ref.
- Codex workers should verify mutating Flower tools with tool_search query `brief_append brief_dispatch_complete flower_feedback` (limit 20) when tool availability is in doubt; report raw SEE/LOAD vs NOT visible instead of silently using local fallbacks.
- Add a git commit trailer `Brief: #244` to every commit for this brief so flower can exact-link commits back to the brief.