Aventuras/docs/followups.md

Follow-ups

Top-level ledger of active outstanding items — design questions or work the current milestone (v1) needs answered, or that block other v1 work. Resolved items are removed (not crossed out); the commit that resolves an item carries the resolution narrative.

Items confirmed for a future milestone or parked indefinitely pending signal live in parked.md. Movement between the two files is normal as scope clarifies; see conventions.md → Followups vs parked for the placement rule.

Data-model

• Implement mentioned places. Designed 2026-10-16 (exploration record); the spec is canon: classifier.md → Mentioned places for the setting, the pass's place tree, its newPlaces list, the row, its parent and the matcher; generation-pipeline.md → No-gate write phase for a pass writing only when no turn is in flight on its branch; and story-settings.md → Classifier for the toggle. Three things the code must make sure of: a turn can't start between a pass's check and the end of its burst, and waits rather than being refused; the pass's planning inside its lock checks the stores still hold its branch, since nothing found cancels a pass when its story closes (triage carries the older character path); and the embedding sync stage and the background embed worker write only vectors and embedding_stale during a turn, which the canon's "nothing but the turn writes its branch's entities" assumes and the design didn't check.

• The periodic classifier creates factions. Factions follow the character path: a new-faction list in the extraction, reconciled by Layer B (classifier.md → Disambiguation on new-character mentions) with the same matcher, flag, partner and reason, plus membership facts writing characters' faction_id, which the authorship contract gives the classifier and nothing machine-writes yet. Membership facts make a pass write entities.state, which a World Save writes whole from the row as the pane rendered it, so a Save can overwrite a pass's membership (cadence.md → User edits and classifier writes); the design settles how the two merge. Open: re-checking the parked closure gap for the faction ids a pass writes into state. Raised 2026-10-10; mentioned places split off and were designed 2026-10-16.

• Chapter-close agent design. Chapter close is designed in memory/chapter-close.md, but not concretely enough to implement. Promoted from the developer's notes 2026-10-10, with an addition: upkeep of the locations and items the per-turn writer creates with only a name, a short description and a parent, and of the places a pass creates from mentions (classifier.md → Mentioned places), meaning their state (condition), keywords and a description refresh. A refresh reverses the authorship contract's user-only description (data-model.md → Authorship contract), so the design decides whether chapter close may rewrite one. It never retires a place: a destroyed place stays active, its destruction a condition (data-model.md → LocationState shape).

• Prompt content pass. The system and user halves moved today's prompts into the new shape without rewriting them, and the content still needs writing: the narrator's standing instructions (its role, the story's mode and lead), which today are one output-format line; the wizard's system halves, empty because each shared context macro mixes the output contract with grounding that changes as the user fills the wizard in, so each splits into a contract macro and a grounding macro; and the blocks the split left in a user half only because they point at its content by position. The narrator's output-format line also left the end of the prompt for the system half, unmeasured; the pass checks where it reads best. v1 work, since the shipped prompts have to be good, once the halves land. Raised 2026-10-11.

  The pass also takes the whitespace and wording nits the halves PR's reviews found in the bundled prompts, all older than the split (routed from triage 2026-10-11):

  • the In-scene loop leaves two blank lines before the next heading in the narrative (per-turn.ts), the fallback classifier (piggyback-fallback-classifier.ts) and the suggestion refresh (suggestion-refresh.ts);
  • a Setting, Genre or Tone the user starts with a newline renders a blank line under its heading;
  • the Gregorian calendar line reads "time in seconds (1 seconds per second)", now inside the cached system half;
  • the periodic classifier's Known entities line ends on a dangling dash for an entity whose description is the empty string;
  • the fallback classifier's roster leaves a blank line between its active and staged entries;
  • the suggestion refresh's In scene list prints an empty line under an entity with no description;
  • a place name with a newline breaks the location map's tree: the rest of the name lands at column 0, where it reads as a top-level place (lib/world/location-map.ts). A retired reason is already flattened to one line there; the name isn't (raised 2026-10-15 by the retired and disabled places slice review).

UX

• Per-turn token usage breakdown. Every turn records the tokens each section of its prompt used (in-scene and retrieved entities, the location map, the story history, retrieved happenings, lore, threads, the instructions and so on) in its entry's metadata, and a UI shows them. Today an entry keeps only totals (metadata.tokens), and the Memory probe's per-pool numbers (memory/probe.md) cover only retrieval's pools and the structural floor, and only on captured turns; the design should build on the probe's accounting rather than beside it, and shows whether the location map needs collapsing as a story grows. The breakdown also records each call's cache read and write tokens (usage.inputTokenDetails), the only measure of whether a cache marker pays. Wanted in v1, design deferred. Raised by the developer 2026-10-10.