feat(D3c): chaptered narrative (story arcs instead of FIFO trim)

[chiruu12]

D3c — chaptered narrative. (Supersedes #37, which auto-closed when its base #35 merged; rebased onto main, history preserved as 5 small commits.)

Replaces the FIFO 800-char narrative trim with story arcs: the open narrative seals into compact Chapter summaries on overflow (carrying goal text + an unambiguous %Y-%m-%d date span), and the preamble shows a "Story so far" section. AgentIdentity.full_narrative() keeps life-summary biographies complete.

Includes the review fixes from #37: strict MAX_NARRATIVE bound (lone oversized entry capped); life-summary regression fixed; richer chapter summaries + unambiguous dates (Greptile).

Verified: 1013 tests pass, ruff/format/mypy/mkdocs clean.

[Copilot]

Pull request overview

Implements D3c “chaptered narrative” for AgentIdentity, replacing FIFO trimming with sealing overflowing narrative into compact Chapter summaries and surfacing those summaries in prompts and life summaries.

Changes:

• Add Chapter model + chapters field on AgentIdentity, plus full_narrative() for retrieving the complete story (chapters + open narrative).
• Update narrative maintenance to seal the open narrative into chapters on overflow (strict MAX_NARRATIVE bound, capped chapter list).
• Render chapter summaries in the identity preamble (“Story so far”) and include full narrative in life summaries; add tests/docs for the new behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
tests/agents/test_identity.py	Adds coverage for chapter model round-trip, sealing behavior, full_narrative(), and preamble rendering.
src/hive/world/life_summary.py	Switches life summaries to include the full narrative (chapters + open narrative).
src/hive/agents/identity.py	Introduces chapters, sealing logic, preamble rendering updates, and full narrative composition.
docs/guide/persona.md	Documents narrative chaptering and how it appears in prompts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

Replaces the previous FIFO 800-character trim on AgentIdentity.narrative with a chaptered story-arc system: when the open narrative overflows it is sealed into a compact Chapter model (carrying a date span and goal theme) rather than dropping the oldest lines. The full history is composed back for life-summary biographies via full_narrative(), and the LLM preamble gains a "Story so far" section showing the five most-recent chapter summaries alongside the current open window.

• Chapter is a new Pydantic model appended to AgentIdentity.chapters; legacy identities (no chapters field) deserialise cleanly with an empty list.
• _seal_chapter computes monotonically incrementing index values, builds a semantically rich summary (date span + first→last goal arc), and trims to MAX_CHAPTERS=20 by dropping the oldest when the cap is exceeded.
• 175 new tests covering sealing, bounds, monotonicity, MAX_CHAPTERS trim, newline normalisation, preamble rendering, and full-narrative composition.

Confidence Score: 5/5

Safe to merge. The sealing logic is correct, all size bounds hold, and legacy identities without chapters deserialise cleanly.

The update_narrative rewrite correctly enforces MAX_NARRATIVE at every code path: oversized single entries are capped before the sealing check, the sealing condition accounts for the newline separator, and _seal_chapter always clears the narrative (including the defensive empty-lines path). Chapter indices are monotonically increasing even after MAX_CHAPTERS trimming. The full_narrative() fix in life_summary.py correctly restores the biography regression. The 175-test suite covers all key invariants including the previously-missing MAX_CHAPTERS trim path.

No files require special attention.

Important Files Changed

Filename	Overview
src/hive/agents/identity.py	Core change: adds Chapter model, _seal_chapter, full_narrative(), and update_narrative rewrite. Logic is correct — bounds hold, indices are monotonic, defensive narrative-clear on empty-lines path is present, and newline normalization prevents multi-line entries from corrupting per-line counting.
tests/agents/test_identity.py	New test file (175 lines) covering all major paths: sealing threshold, MAX_NARRATIVE bound, oversized single entry, chapter-index monotonicity, MAX_CHAPTERS trim, goal-text in summaries, newline normalisation, full_narrative composition, and preamble rendering with and without chapters.
src/hive/world/life_summary.py	One-line fix: passes identity.full_narrative() instead of identity.narrative to include sealed chapter summaries in life biographies — correct fix for the regression noted in previous reviews.
docs/guide/persona.md	Adds a short 'Narrative & chapters' section explaining the story-arc design. Documentation accurately reflects the implementation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["update_narrative(agent_id, goal_text, outcome)"] --> B["load identity from disk"]
    B --> C{identity found?}
    C -- No --> Z["return (no-op)"]
    C -- Yes --> D["normalize newlines in goal_text / outcome"]
    D --> E["build entry string [YYYY-MM-DD] goal: outcome"]
    E --> F{len entry > MAX_NARRATIVE?}
    F -- Yes --> G["truncate entry to MAX_NARRATIVE-1 + ellipsis"]
    F -- No --> H{narrative non-empty AND narrative+entry+1 > MAX_NARRATIVE?}
    G --> H
    H -- Yes --> I["_seal_chapter(identity)"]
    H -- No --> J["append entry to narrative"]
    I --> I1["collect non-empty lines from narrative"]
    I1 --> I2{any lines?}
    I2 -- No --> I3["narrative = '' defensive clear, return"]
    I2 -- Yes --> I4["compute date span started/ended"]
    I4 --> I5["extract first_goal / last_goal via _entry_goal()"]
    I5 --> I6["build Chapter summary"]
    I6 --> I7["append Chapter to identity.chapters"]
    I7 --> I8{len chapters > MAX_CHAPTERS?}
    I8 -- Yes --> I9["trim: keep last MAX_CHAPTERS"]
    I8 -- No --> I10["identity.narrative = ''"]
    I9 --> I10
    I10 --> J
    J --> K["save identity to disk"]

Loading

_{Reviews (2): Last reviewed commit: "fix(D3c): normalize newlines in entries ..." | Re-trigger Greptile}