feat(roles): side-role system prompts load from roles/*.md over shared identity (#1729)

[ozand]

Closes #1729. ADR-022 rule 2: code assembles, code does not author.

The eight non-executor callers carried their system prompt as a Python string literal. None of them shared the agent's identity or soul, and none of the texts could be read or reviewed by the operator without a harness PR. Each literal now lives in roles/<role>.md at the release root, and nanobot/runtime/role_prompt.py assembles

IDENTITY.md (short form) -> SOUL.md -> goals.md -> roles/<role>.md

reusing ContextBuilder.load_block's [missing: X] marker, truncation notice and per-block accounting from #1725 — one convention for an absent or oversized block, not a second one.

Per-role sizes, flags and budgets

Flags follow the issue's 2026-09-18 revision. "Before" is the literal at fa5b9926; "after" is the assembled system message measured from the built string.

Role	Before	After	Δ	identity	soul	charter	role body / budget
proposer	2,045	6,906	+4,861	210	yes	yes	2,045 / 2,600
demand-proposer	1,689	6,550	+4,861	210	yes	yes	1,689 / 2,200
goal-review	1,343	6,204	+4,861	210	yes	yes	1,343 / 1,800
curator	911	2,725	+1,814	210	yes	—	911 / 1,600
narrator	503	2,317	+1,814	210	yes	—	503 / 800
strategist	486	703	+217	210	—	—	486 / 800
reflector	602	819	+217	210	—	—	602 / 900
skill-eval	105	322	+217	210	—	—	105 / 300
total	7,684	26,546	+18,862

The three tight-cap roles grow by exactly the short identity plus one separator (+217), which is the bound the revision asked for: strategist runs under _MAX_PAYLOAD 18,000, skill-eval under MAX_TASK_PROMPT_CHARS 4,000, and reflector under input_fit. The short identity form is the first paragraph of IDENTITY.md, 210 chars against the 300-char cap. A test asserts the bound per role rather than trusting the table.

What changed

New files

• roles/proposer.md, roles/demand-proposer.md, roles/goal-review.md, roles/curator.md, roles/narrator.md, roles/strategist.md, roles/reflector.md, roles/skill-eval.md — each the literal verbatim under # Role: <name>, with the output-format contract intact and budget_chars in front matter.
• nanobot/runtime/role_prompt.py — build_role_system_prompt(role, *, with_charter, with_soul, identity_short, release_root, role_text, substitutions) returning (text, telemetry) where telemetry is {role, blocks: {name: chars}, missing: [...], truncated: [...], chars, with_charter, with_soul}; plus load_role_text, resolve_release_root, role_budget, system_chars, and ROLE_FLAGS as the single place the per-role expectation lives.
• tests/test_role_prompt.py — 62 tests.
• tests/fixtures/role_literals_pre_1729.json — the eight literals as they stood at fa5b9926.

Call sites replaced

• nanobot/runtime/llm_proposer.py — _PROPOSER_SYSTEM_PROMPT and _DEMAND_PROPOSER_SYSTEM_PROMPT are now loaded, not authored; propose() prepends identity, soul and charter once via _role_name_for(role_body), so the system_prompt= argument keeps carrying only the role body and every existing caller and test keeps working.
• nanobot/runtime/goal_review.py — _GOAL_REVIEW_SYSTEM_PROMPT loaded from roles/goal-review.md.
• nanobot/runtime/knowledge_curator.py, nanobot/runtime/reflector.py, nanobot/runtime/strategist.py, nanobot/runtime/skill_eval_harness.py — inline system = (...) replaced by build_role_system_prompt(...).
• scripts/journal_story.py — _NARRATOR_SYSTEM_PROMPT becomes _narrator_system_prompt().

Telemetry

nanobot/observability/llm_telemetry.py:record_llm_call gains system_prompt_chars: int | None = None, written on every row (None when the caller did not measure). All six recording call sites pass it, measured from the system message the caller built via system_chars(messages) — never from state/llm_calls/prompts, which caps well below a full prompt. A test drives a measured row and an unmeasured one and asserts [703, None].

Two decisions worth reviewing

Meaning preserved, not reworded. The parity test compares every role file against the fixture after whitespace normalisation; the files are hard-wrapped for a human reader, and only the words are the contract. Rewording a role is a later PR with its own replay (ADR-011 rule 3), and it has to update the fixture deliberately.

A RELEASE_ROOT without roles/ is not a release tree for roles. Several existing fixtures set RELEASE_ROOT to a minimal tree holding only goals.md (for example tests/test_strategist.py:34). Reading roles out of such a tree reports eight missing files and reads like a broken deploy, so resolution falls through to the package tree in that case; an explicit release_root= argument always wins outright. Documented in the function and covered by two tests.

The proposer role files carry a {commit_surfaces} placeholder filled from MUTATION_POLICY at load time, so those two prompts cannot drift from the policy the way a copied literal could — the drift #1731 already fixed once. The import-time validate_rendered_surfaces check now validates the prompt itself as well as the marker, and skips when the role file is absent and the body is a marker.

The narrator keeps the ADR-016 rule 1 barrier by construction: the assembler reads the release files and nothing else, so it has no reader for any channel figure. Tests assert it on both the assembled prompt and the module source.

Packaging needs no change: deploy_release.sh builds the archive with git archive from the commit, so roles/ ships the same way IDENTITY.md and SOUL.md did in #1735.

Tests

tests/test_role_prompt.py                                          62 passed
tests/test_llm_proposer*.py test_fallback_lane test_mutation_policy
  test_goal_review test_proposer_model_split                      394 passed
tests/test_knowledge_curator*.py test_curator_*.py test_reflector*.py
  test_strategist*.py test_skill_eval_harness test_journal_story
  test_publication_intake test_side_role_cliffs                   278 passed, 2 skipped
tests/test_context_prompt_budget.py tests/test_llm_telemetry.py     11 passed
tests/test_llm_calls_report.py test_llm_prompt_recording
  test_cycle_id_join test_doctor test_bridge_executor_llm_error     72 passed

Every pre-existing test passes unchanged. One needed a decision rather than an edit: test_build_strategist_prompt_includes_triz_and_hadi exercised the RELEASE_ROOT-without-roles/ case above, and the resolution rule is what makes it pass.

Follow-ups, not done here

• Prompt ontology tests: each rule once, AGENTS.md scope, surface parity, no guidance without capability #1726 owns tests/test_prompt_ontology.py; two fingerprints belong in its table and are deliberately not added here: You are the eeebot and Return ONLY. tests/test_role_prompt.py::TestNoLiteralsLeft covers the eight role openings in the meantime.
• Two technical prompts are allowlisted, named, and bounded, not silently skipped: nanobot/agent/memory.py (96 chars, "You are a memory consolidation agent") and nanobot/heartbeat/service.py (73 chars). Each is one sentence telling a model what shape to return for one mechanical call — no persona, no procedure, no values. A test asserts they stay under 120 chars, so one growing into a role fails loudly. Their final disposition belongs with Prompt ontology tests: each rule once, AGENTS.md scope, surface parity, no guidance without capability #1726's fingerprint table. nanobot/utils/evaluator.py:38 (441 chars, the notification gate) is the one real candidate to become roles/notification-gate.md; it is not one of the eight this issue names.
• build_task (Add OPERATING.md: cycle rules in one release-owned file, build_task and AGENTS.md stop restating them #1723 part b) is untouched; another agent owns it.

🤖 Generated with Claude Code

[ozand]

Rebased onto 96a450a0 (#1744) and fixed the red check.

tests/test_trainer_no_direct_mutation::test_only_the_named_gate_writer_touches_lessons_or_skills_paths failed because role_prompt imported ContextBuilder for load_block / _trim_lines. That import pulls the memory store, the skills loader and the tool registry into the import closure of every trainer seed module, and the guard then sees nanobot.utils.helpers:sync_workspace_templates as a lessons/skills writer reachable from the reflector. The guard is right: the reachability was real, and widening it to read two markdown files is not a trade worth making.

Fix (39cb0b54): the two primitives move to nanobot/agent/block_loader.py — no state, no I/O beyond the file each call is given. ContextBuilder keeps load_block and _trim_lines as staticmethod aliases, so every existing caller and test is untouched, and role_prompt imports only the small module. 107 tests pass across the trainer guard, the role prompts, the ontology loader, the prompt fit and the system-prompt sections.

The full suite run on this branch hit one unrelated failure, tests/test_deploy_activation_exit_class::test_gate_transport_exit_in_journal_does_not_roll_back (a deploy-script test that touches none of these files); checking whether it is red on main as well and will report before merge.