docs: DR for prompt sourcing & composition (S + D) with BACKBEAT

docs/decisions/2025-09-06-prompt-sourcing-and-composition.md

@@ -0,0 +1,60 @@
+ucxl.address: ucxl://arbiter:design@CHORUS:prompt-sourcing/#/docs/decisions/2025-09-06-prompt-sourcing-and-composition.md
+version: 2025-09-06T00:00:00Z
+content_type: text/markdown
+metadata:
+  classification: internal
+  roles: [arbiter, maintainer]
+
+# Decision Record: Prompt Sourcing and Composition (S + D)
+
+## Problem
+Agents used a hardcoded system prompt ("You are a helpful assistant.") and scattered inline prompt strings. We need configurable system prompts per agent role and a shared, generic instruction set that can be modified without rebuilding images or redeploying.
+
+## Decision
+Adopt externalized prompt sourcing via a Docker-bound directory. Compose each agent's final system prompt as S + D:
+- S (System Persona): Per‑role system prompt loaded from YAML files in a mounted directory.
+- D (Default Instructions): A shared instruction file defining standards for HMMM, COOEE, UCXL, and BACKBEAT, including JSON message shapes and usage rules.
+
+The runtime loads S and D at startup and sets the LLM system message accordingly. Updates to S or D require only changing files on the host volume.
+
+## Implementation
+- Directory: `CHORUS_PROMPTS_DIR` (e.g., `/etc/chorus/prompts`), bind-mounted read‑only via Docker/Swarm.
+- Files:
+  - Roles (YAML): one or many files; merged by role id. Example at `prompts/roles.yaml`.
+  - Defaults (Markdown): `defaults.md` (or `defaults.txt`). Override path via `CHORUS_DEFAULT_INSTRUCTIONS_PATH`.
+- Loader: `pkg/prompt`
+  - Scans `CHORUS_PROMPTS_DIR` for `*.yaml|*.yml` and `defaults.md`.
+  - Exposes `ComposeSystemPrompt(roleID)` → S + D.
+- Reasoning: `reasoning.SetDefaultSystemPrompt()` sets the default system message for provider calls.
+- Wiring: in `internal/runtime/shared.go` during initialization, we:
+  - Initialize prompts via env
+  - If `Agent.Role` is set, attempt S + D; else D only
+  - Apply via `reasoning.SetDefaultSystemPrompt`
+- Commit reference: 1806a4f
+
+## Default Instructions D (Summary)
+- Operating policy: precision, verifiability, minimal changes, UCXL citations, safety.
+- HMMM: use for collaborative reasoning; publish JSON to `hmmm/meta-discussion/v1`.
+- COOEE: use for coordination; publish `cooee.request` and `cooee.plan` JSON to `CHORUS/coordination/v1`.
+- UCXL: read by address; write decisions with the decision bundle envelope; never invent paths.
+- BACKBEAT: emit beat-aware timing/phase events with correlation IDs; phases `prepare|plan|exec|verify|publish`; events `start|heartbeat|complete`; include budget/elapsed and link to HMMM/COOEE IDs when present.
+- Full JSON shapes are stored in `prompts/defaults.md`.
+
+## Usage
+- Mount in Docker:
+  - `-v /srv/chorus/prompts:/etc/chorus/prompts:ro`
+  - `-e CHORUS_PROMPTS_DIR=/etc/chorus/prompts`
+  - Optional: `-e CHORUS_DEFAULT_INSTRUCTIONS_PATH=/etc/chorus/prompts/defaults.md`
+- Select role per container: `-e CHORUS_ROLE=arbiter` (example)
+- Modify role YAML or `defaults.md` on the host; restart container to pick up changes (no rebuild).
+
+## Future Work
+- Hot-reload via fsnotify or `/api/prompts/reload` endpoint.
+- WHOOSH integration endpoint to enumerate roles and return composed S + D per team member.
+- Per-role overrides for models/capabilities applied to `AgentConfig`.
+
+## Impact
+- Prompts are now ops‑tunable via mounted files, reducing deployment friction.
+- Consistent, centralized guidance for HMMM, COOEE, UCXL, and BACKBEAT across all agents.
+- Backward compatible: if no files are mounted, system uses a sane fallback.
+