pal-e-docs

Review: Evolve main session agent: Ava → Hem

review-1085-2026-04-25 Doc

review approved
Project

Verdict: APPROVED

Board item: #1085 (board-pal-e-agency) | Forgejo issue: forgejo_admin/claude-custom#243 | Type: Feature

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Lucas decision in pal-e-platform session 2026-04-24, evolution rationale documented
  • [x] Repo — forgejo_admin/claude-custom
  • [x] User Story — full As/I want/So that
  • [x] Context — explains Ava sprawl pattern, Hemingway+military comms inversion, prior precedent
  • [x] Environment — repo, hook path, exact line, API base, enumeration tool, prior precedent slug
  • [x] File Targets — hook line, CLAUDE.md, pal-e-docs note set (CREATE/UPDATE/BULK UPDATE)
  • [x] Test Expectations — 4 verifiable steps
  • [x] Checklist — 10 items
  • [x] Acceptance Criteria — 7 items
  • [x] Constraints — ordering dependency, audit-trail preservation, worktree
  • [x] Out of Scope — peer agents, MEMORY.md, Hem persona authorship
  • [x] Related — prior precedent, validation note, deprecating note, paradigm, design convention

Traceability

  • [x] story:pm-scope — verified in project-pal-e-agency user-stories table (PM/Ava role: triage boards, scope work, dispatch agents, /update-docs). Persona-evolution work directly affects PM execution; appropriate story link.
  • [x] arch:agent — backing note agent-paradigm exists (Layer 5: Agents in the 5-layer model). Persona swap at the Agent layer; appropriate arch link.
  • [x] Forgejo issue — claude-custom#243 verified open, body fetched, fully populated.
  • [x] type:feature, scope:unplanned — labels consistent with ticket type.

File Targets

  • [x] ~/.claude/hooks/session-start-context.sh:246 — VERIFIED. Line 246 reads "${PAL_E_API_URL}/notes/agent-ava" 2>/dev/null) || true. Exact one-line patch: agent-ava → agent-hem.
  • [x] ~/.claude/CLAUDE.md — VERIFIED. 3 references at lines 1 ("# Ava — Strategic Partner"), 3 ("You are Ava..."), 7 ("get_note(slug=\"agent-ava\")"). All require update.
  • [x] agent-ava note — exists (id 998, project pal-e-agency, status active). Will be flipped to deprecated with redirect content.
  • [x] agent-hem note — does NOT exist (correct precondition; must be CREATEd before hook repoint per ordering constraint).
  • [x] Bulk-update enumeration strategy — search_notes(query="Ava") is the documented enumerator. Filter rule "exclude review-* and validation-*" is explicit. Pattern mirrors validation-247-2026-03-29 (Betty Sue → Ava precedent referenced).

Repo Placement

OK. Code edits go to forgejo_admin/claude-custom (the only Forgejo repo in scope — pal-e-agency project has repo_url: null, so doc edits land via pal-e-docs API only, not a separate Forgejo issue). Single PR on claude-custom + bulk pal-e-docs writes is the correct split.

Dependencies

Hard ordering dependency (already documented in Constraints): create agent-hem note BEFORE patching the hook. Session-start-context.sh fetches the slug at SessionStart; a missing slug yields a silent no-op personality block, which would degrade every new session.
External dependency: persona content authorship is explicitly Out of Scope (the dev agent must produce the Hem definition as part of AC #1). This is a soft scope risk — see Recommendation [SCOPE] below.
No board-level blockers. No item is in in_progress on board-pal-e-agency that conflicts.

Acceptance Criteria

All 7 AC are agent-verifiable: note existence (API GET), line-grep on hook + CLAUDE.md, status field check, search_notes enumeration with exclusion filter, fresh-session inspection, validation note publication. Test Expectations align 1:1 with AC. No untestable criteria.

Blast Radius

Personality injection is platform-wide — every Claude Code session in every repo on this machine reads from session-start-context.sh. A broken slug or malformed Hem persona affects all main-session work until rolled back. Mitigations are present: ordering constraint, validation note as final AC.
20+ doc references per ticket body. The Betty Sue → Ava precedent (validation-247-2026-03-29) is named as the surgical-update template. Risk is acceptable given the proven precedent.
Subagent context inheritance — the SubagentStart hook may inject the personality block into spawned agents. Worth a spot-check during validation that subagents receive Hem context, not stale Ava text. Calling out as a validation hint, not a body fix.

Decomposition Assessment

5-minute rule: File targets = 2 (hook + CLAUDE.md) plus N pal-e-docs notes (~20). Single repo. AC count = 7. Estimated agent time = 15–25 minutes (dominated by bulk doc updates).
Verdict: Borderline. The bulk-doc-update pattern is well-precedented (Betty Sue → Ava ran as a single agent successfully). Splitting would add coordination overhead without quality gain. No decomposition required, but the dev agent should batch the doc-updates phase and the code-edit phase as logical sub-steps within one PR.

Recommendation

APPROVED — ready to advance backlog → todo. Two non-blocking notes for the dev agent (do not require ticket refinement):
  • [SCOPE] Persona content authorship is Out of Scope per ticket. Lucas should provide voice exemplars or approve the Hem persona draft before merge — this is a Lucas decision gate, not an agent deliverable boundary issue.
  • [BODY] Optional: add an explicit validation step to verify SubagentStart hook injects Hem (not just SessionStart). Not required — covered implicitly by "fresh session" Test Expectation.
Ticket scope is solid, traceability complete, file targets verified, precedent established. Ready to dispatch once it reaches next_up.