@deftai/directive-content 0.55.0

package/patterns/multi-agent.md

@@ -0,0 +1,278 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered pattern -->
+<!-- Source of truth: packs/patterns/patterns-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every pattern: task packs:slice patterns by-trigger --trigger <kw> (or list) -->
+
+# Multi-agent identity separation pattern (#983)
+
+> Status: stable pattern, v1 docs-only. v1 deliberately scopes to a single
+> shared bot/App credential for all workers; per-worker token rotation is
+> deferred to a follow-up. Per #983 non-goals.
+
+This pattern lays out *whose* GitHub identity dispatched swarm workers
+should authenticate as, *why* that should not be the maintainer's PAT,
+and *how* operators provision and rotate the worker credential.
+
+It is the credential-separation track that was carved out of #976
+(`fix(scm,tests): eliminate remaining GraphQL-backed scm.py / live SCM
+smoke bucket drain after #961`). #976 owns the REST migration; this
+pattern owns the orthogonal identity separation. The two tracks are
+complementary: REST migration reduces GraphQL demand on the shared
+bucket, identity separation prevents human and machine traffic from
+sharing one bucket in the first place.
+
+## Why this matters
+
+Today, swarm workers and the maintainer share a single GitHub Personal
+Access Token (PAT). One PAT serves the maintainer's interactive review
+flow AND every worker spawned by `task swarm:*` / `start_agent` /
+`oz agent run`. The operational consequences observed in the
+2026-05-07 multi-agent session and again on 2026-05-08 are concrete:
+
+- **Bucket coupling**: GitHub's GraphQL bucket is **5,000 req/hr per
+  identity**. A swarm of N workers + the maintainer's terminal share
+  one bucket. When workers exhaust it (the documented failure mode for
+  the PR #652 / #561-class merge cascades), the maintainer's
+  `gh issue create` and `gh pr view` start failing with
+  `GraphQL: API rate limit already exceeded` -- the human is rate-
+  limited by their own swarm.
+- **Audit conflation**: every commit, comment, PR open, issue close,
+  and review submission attributes to the same `actor.login`. Forensic
+  separation ("which action was the maintainer vs. an autonomous
+  worker?") requires correlating timestamps and dispatch-envelope
+  prompts rather than reading the GitHub event stream directly.
+- **Credential blast radius**: a worker's prompt envelope is by
+  definition reviewable / loggable / inspectable -- prompts leak more
+  readily than secrets. Today a leaked worker prompt acts with the
+  full scope of the maintainer's PAT (issue close, PR merge, release
+  publish, branch protection bypass), not the narrow scope a worker
+  actually needs (issues:write, pulls:write, contents:read).
+
+Reducing GraphQL demand (#976 REST migration) only solves bucket
+*pressure*. It does not solve bucket *coupling*, audit conflation, or
+blast radius. Those require partitioning the identity itself.
+
+## The pattern
+
+### Identity model
+
+- ! Workers MUST authenticate as a **distinct GitHub identity** from
+  the maintainer. Two acceptable shapes:
+  1. **GitHub App installation token** (preferred). The deft project
+     installs a GitHub App granting the minimum scopes; workers
+     consume an installation token derived from the App's private key.
+     Tokens are short-lived (~1 hour) and auto-rotated by GitHub.
+  2. **Bot account PAT**. A dedicated GitHub user account (e.g.
+     `deft-swarm-bot`) with its own PAT. Lower setup cost, but tokens
+     are long-lived until manually rotated, and the bot account
+     consumes a real GitHub seat.
+- ! Maintainer PATs MUST be reserved for human-driven work: review,
+  merge, release publication, manual triage. Worker dispatch envelopes
+  MUST NOT inject a maintainer PAT.
+- ⊗ Workers MUST NOT fall back to the host's `gh auth status` token.
+  The dispatch envelope is the contract; an implicit fallback re-
+  introduces the coupling this pattern eliminates.
+
+### Bucket partitioning model
+
+| Bucket               | Owner                | Use                                                |
+|----------------------|----------------------|----------------------------------------------------|
+| Maintainer GraphQL   | Maintainer PAT       | Human review, PR open/merge/ready, manual triage   |
+| Maintainer core REST | Maintainer PAT       | `gh api` reads outside swarm context               |
+| Worker GraphQL       | Bot account / App    | `markPullRequestReadyForReview`, `addPullRequestReview` (the only GraphQL surfaces a worker should hit; see #976 + #961) |
+| Worker core REST     | Bot account / App    | All other reads / mutations via `gh_rest.py` REST helpers |
+
+Each bucket is 5,000 req/hr (REST `core` and GraphQL each). With
+identity separation the maintainer's two buckets are untouched by
+swarm activity, and N workers share *their own* two buckets.
+
+The bucket partition only delivers value when paired with the #976
+REST migration: workers that still route reads through GraphQL
+(`gh issue view --json`, `gh pr view --json`, `gh pr ready`) will
+exhaust their own GraphQL bucket within minutes under N concurrent
+poll loops. REST-by-default per `templates/agent-prompt-preamble.md`
+S5 keeps the worker GraphQL bucket reserved for the unavoidable PR
+state-mutation operations.
+
+### Dispatch-envelope credential rule
+
+The canonical preamble at `templates/agent-prompt-preamble.md` carries
+this rule verbatim alongside the existing REST-default,
+max-1-Draft-toggle, and rate-limit-throttle rules:
+
+> Workers MUST consume the GitHub credential injected by the dispatcher
+> (typically `GH_TOKEN` in the prompt-supplied env). Workers MUST NOT
+> fall back to the host's `gh auth status` token. If `GH_TOKEN` is
+> unset and no other dispatcher-supplied credential is present, the
+> worker MUST fail loud with a clear error rather than silently
+> running under the host identity.
+
+The rule is enforced at two points:
+
+1. **Dispatch time** (orchestrator side). The orchestrator (swarm
+   skill, monitor agent, scheduled run) injects the worker
+   credential into the dispatch envelope -- usually as `GH_TOKEN` in
+   the env, with the maintainer's `gh auth` state untouched. Workers
+   inherit this env at spawn time.
+2. **Worker side**. The worker's first action (after AGENTS.md read)
+   verifies `GH_TOKEN` is set and matches the expected bot/App
+   identity (e.g. `gh api user --jq .login` returns the bot login).
+   Mismatch is a hard refusal: stop the tool loop, send `BLOCKED:
+   identity mismatch` to the parent.
+
+The two-sided enforcement means a missing/malformed credential surfaces
+at the earliest possible point rather than mid-dispatch when the worker
+has already started writing files.
+
+### Permission scoping
+
+! The worker credential MUST be scoped down to the minimum needed:
+
+- `issues:write` -- open / close / comment / label
+- `pulls:write` -- open / merge / review / comment
+- `contents:read` -- read repo contents (for diff context)
+- `metadata:read` -- standard for any GitHub App
+- ⊗ `contents:write` -- workers MUST NOT push commits directly under
+  the worker identity. Pushes happen via the maintainer (interactive
+  review of the worker's diff) or via the GitHub App's restricted
+  contents:write scope on a specific bot-owned ref pattern.
+- ⊗ `admin:*` / `repo` (broad) -- workers MUST NOT have admin scopes.
+  Branch protection bypass, label/milestone management, secret
+  rotation -- all maintainer-only.
+
+The maintainer PAT keeps the broader scope it has today (`repo`,
+`workflow`, etc.). The narrowness of the worker scope is half the
+blast-radius mitigation; the other half is short-lived credentials
+(GitHub App installation tokens auto-rotate ~1 hour; bot PATs MUST be
+rotated quarterly per the runbook below).
+
+## Operator runbook
+
+### Provisioning a worker identity
+
+#### Option A: GitHub App (preferred)
+
+1. Create a new GitHub App at
+   `https://github.com/organizations/<org>/settings/apps/new`
+   (account-level path: `https://github.com/settings/apps/new`).
+2. Grant the **minimum** permissions enumerated in
+   "Permission scoping" above. Decline every other permission.
+3. Subscribe to no events (workers consume the API; they do not need
+   webhook delivery).
+4. Generate and download a private key (`.pem`). Store it in
+   `secrets/swarm-app.pem` outside the repo (the deft `secrets/`
+   convention is `.gitignore`d by default per the repo conventions).
+5. Install the App on the deft repository.
+6. Note the App ID and Installation ID; both are required to mint
+   installation tokens at dispatch time.
+7. The dispatcher mints an installation token via
+   `POST /app/installations/<installation-id>/access_tokens` (the
+   private-key-signed JWT flow). Each minted token lives ~1 hour;
+   spawn-burst refreshes are cheap.
+
+#### Option B: bot account PAT
+
+1. Create a new GitHub user account (e.g. `deft-swarm-bot`). Email
+   address can be a `+swarmbot` alias on the maintainer's account.
+2. Add the bot account as a repository collaborator with **Write**
+   access (NOT Maintain or Admin).
+3. Generate a fine-grained PAT under the bot account with the scopes
+   enumerated in "Permission scoping". Set expiry to 90 days.
+4. Store the PAT in `secrets/swarm-bot.env` as
+   `SWARM_GH_TOKEN=<value>`. Reference from dispatcher via
+   `Get-Content secrets/swarm-bot.env` or equivalent at dispatch
+   time; never paste inline.
+
+### Wiring the dispatcher
+
+The orchestrator (swarm skill, monitor agent, `start_agent`/`oz`
+invocation, scheduled run) loads the worker credential and injects it
+into the worker's env:
+
+```pwsh path=null start=null
+# Option A (GitHub App): mint installation token at dispatch time.
+$jwt = uv run python scripts/swarm_mint_jwt.py --app-id $env:DEFT_SWARM_APP_ID --pem secrets/swarm-app.pem
+$inst_token = (gh api -X POST "/app/installations/$env:DEFT_SWARM_INSTALLATION_ID/access_tokens" -H "Authorization: Bearer $jwt" --jq .token)
+start_agent ... -e GH_TOKEN=$inst_token
+
+# Option B (bot PAT): inject from secrets/swarm-bot.env.
+$bot_token = (Get-Content secrets/swarm-bot.env | Where-Object { $_ -like 'SWARM_GH_TOKEN=*' }) -replace '^SWARM_GH_TOKEN=', ''
+start_agent ... -e GH_TOKEN=$bot_token
+```
+
+Token-mint plumbing (`scripts/swarm_mint_jwt.py`) is intentionally not
+shipped in v1 -- the runbook above is operator-facing guidance, not
+deft-supplied automation. v1 is documentation-only per #983 non-goals.
+Operators MAY automate token minting in their own dispatcher; the
+contract this pattern pins is the env-var injection.
+
+### Rotation and recovery
+
+#### Routine rotation
+
+- **GitHub App tokens**: auto-rotate ~1 hour. No operator action
+  needed unless the App's private key is compromised.
+- **Bot PAT**: quarterly rotation. Update `secrets/swarm-bot.env`
+  and revoke the prior PAT. Verify the new token via
+  `gh api user --jq .login` returns the bot login.
+
+#### Compromise recovery (leaked worker token)
+
+1. Immediately revoke the leaked credential:
+   - GitHub App: rotate the private key (Settings -> Apps -> Your
+     deft-swarm App -> Generate a new private key, then delete the
+     compromised key).
+   - Bot PAT: revoke at
+     `https://github.com/settings/tokens` under the bot account.
+2. Audit the bot's recent activity: `gh api
+   /users/<bot-login>/events/public --jq
+   '.[] | {repo, type, created_at}'`. Investigate any action outside
+   the expected swarm workflow.
+3. Provision a replacement credential per the provisioning steps
+   above and update the dispatcher.
+4. File an incident vBRIEF in `vbrief/proposed/` documenting the
+   compromise, scope of activity, and remediation. The vBRIEF
+   becomes the audit artifact.
+
+The maintainer PAT MUST NOT be used as a fallback during the
+compromise window -- doing so re-couples the buckets and re-introduces
+the blast-radius problem this pattern solves.
+
+## Cross-references
+
+- #976 -- remaining GraphQL drain in `scripts/scm.py` + smoke (the
+  REST-migration track this pattern complements; this pattern was
+  carved out of #976's "Complementary mitigation" section)
+- #588 -- agent identity pattern (distinct attestable identity per
+  agent; the conceptual frame this pattern operationalises)
+- #806 -- executor-layer-credentials (secrets bound at invocation
+  layer, not in agent context; the architectural pattern this
+  pattern lands)
+- #585 -- credential hygiene standard for cloud agent dispatch
+  (overlapping with v1, but #585 covers the broader cloud-agent
+  surface; this pattern scopes specifically to swarm workers)
+- #519 -- rate limiting as a first-class architectural constraint
+  for multi-agent guidance (the "shared bucket is the bottleneck"
+  framing that motivates partitioning by identity)
+- #520 -- multi-provider routing as the production solution for
+  large-scale swarms (the LLM-side analogue of this pattern -- LLM
+  providers also rate-limit per identity, and the same partitioning
+  argument applies upstream)
+- #954 / #966 -- canonical orchestrator preamble; the
+  `templates/agent-prompt-preamble.md` rule enforcing the
+  dispatch-envelope credential contract is part of #954's preamble
+  surface and is updated by this issue (#983)
+- AGENTS.md `## Multi-agent orchestration discipline (#954)` -- the
+  REST-default / no-Draft-retoggle / rate-limit-throttle rules this
+  pattern complements
+
+## Non-goals (per #983)
+
+- Per-worker token rotation infrastructure -- a single shared
+  bot/App credential for all workers is acceptable in v1; per-worker
+  identities are deferred to a follow-up.
+- Cross-provider identity (Anthropic, OpenAI, etc.) -- this pattern
+  is GitHub-specific; the LLM-side analogue is #520.
+- Replacing the SCM/REST migration -- #976 owns that track; this
+  pattern is complementary, not a substitute.

package/patterns/prompt-assembly-layer-ordering.md

@@ -0,0 +1,154 @@
+# Prompt assembly layer ordering (#836)
+
+Architectural standard for agents that issue multi-turn LLM API calls
+(OpenAI, Anthropic, Cohere, local models, etc.). It pins the contract
+between the **cached system prefix** (assembled once at session start,
+stable for the session) and the **ephemeral per-turn injections**
+(rebuilt on every API call, never cached). Mixing these two layers
+collapses prefix-cache effectiveness and silently multiplies token
+cost by the number of turns.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**Load when:** the project assembles a system prompt from more than one
+fragment, or relies on provider-side prompt caching (Anthropic prompt
+caching, OpenAI cache hits via stable prefix, vLLM/Anthropic-compatible
+local model caches, etc.), or operates an agent across more than one
+user turn per session.
+
+**Source material:** NousResearch Hermes agent architecture
+(`prompt-assembly.md`); the same separation is documented by every
+major provider's prompt-caching guidance. The rule below codifies it
+as a deft-side standard so agents built with directive inherit the
+discipline by default.
+
+**⚠️ See also**:
+- [./llm-app.md](./llm-app.md) -- LLM application standards (#481); the **Prompt construction** and **Trust tiers** sections of that file are the foundational rules this pattern extends. The trust-tier contract is orthogonal to the cache-tier contract -- a fragment can be system-trust and still be ephemeral (e.g. a per-turn safety overlay), and a fragment can be cached and still be lower-trust (e.g. a frozen RAG snippet); both axes MUST be tracked separately
+- [../context/context.md](../context/context.md) -- the **Write** and **Compress** strategies operationalise the same insight (externalise stable content; reduce per-turn re-injection)
+
+## The invariant
+
+> If it changes per-turn, it is ephemeral. If it is stable for the
+> session, it is cached.
+
+- ! MUST classify every fragment that enters the prompt as either *cached prefix* or *ephemeral injection* at construction time -- a fragment that cannot be classified is ambiguous and ambiguity is itself a defect (the same posture `patterns/llm-app.md` `## Trust tiers` takes on tier classification)
+- ⊗ MUST NOT place a fragment whose content varies per-turn into the cached prefix -- one variable byte invalidates the entire suffix of the cache and forces a cache miss on every turn, multiplying token cost by `N_turns`
+- ⊗ MUST NOT place a fragment that is stable for the session into the ephemeral injection layer -- this re-pays the token cost on every turn for content the provider would otherwise serve from cache
+- ! MUST surface the layer classification alongside the fragment in the assembled prompt log so a future reviewer can audit which fragments lived in which layer (see `## Observability` below)
+
+## Cached prefix -- assembled once at session start
+
+The cached prefix is the prompt's stable, session-scoped opening. It is
+constructed exactly once per session, hashed, and sent verbatim on every
+turn so the provider can serve cache hits against the prefix.
+
+Canonical content for the cached prefix:
+
+1. **Agent identity** -- persona / SOUL.md / system role declaration
+2. **Tool-aware behaviour guidance** -- tool catalogue, calling conventions, refusal rules
+3. **Frozen memory snapshot** -- the session-start memory excerpt (see #832); MUST NOT be edited mid-session
+4. **Skills index** -- the discoverable skills surface (file names, one-line descriptions)
+5. **Context files** -- AGENTS.md, project configuration, repository conventions
+6. **Session timestamp** -- the single timestamp recorded at session start (NOT per-turn)
+
+- ! MUST assemble the cached prefix exactly once at session start; every subsequent API call sends the byte-identical prefix
+- ! MUST hash the assembled prefix and log the hash with the session start event so cache-miss debugging is grounded in a verifiable artefact
+- ⊗ MUST NOT mutate the cached prefix mid-session -- a mutation invalidates the cache for every remaining turn in the session
+- ⊗ MUST NOT inject per-turn metadata (current task, current timestamp, current user message echo, current tool call result) into the cached prefix -- these are ephemeral by definition
+- ~ SHOULD treat the cached prefix as code: version-controlled, code-reviewed, and re-rendered into a queryable log line on every session-start so prefix drift between deploys is visible
+
+### Why ordering within the cached prefix matters
+
+Provider prefix caches are *byte-prefix* caches: the cache hit length is
+the longest byte-identical prefix of the current request against the
+cached entry. A byte that differs at position `k` invalidates the cache
+for every byte from `k` onward. Therefore, within the cached prefix,
+**fragments that change least frequently MUST come earliest**.
+
+Canonical ordering, most-stable to least-stable:
+
+```text
+1. Agent identity              <- changes least (frozen until next deploy)
+2. Tool-aware behaviour guidance
+3. Frozen memory snapshot      <- changes only between sessions (#832)
+4. Skills index                <- changes when skills are added/removed
+5. Context files               <- changes per-project
+6. Session timestamp           <- changes per-session (last in cached layer)
+```
+
+- ! MUST order cached-prefix fragments most-stable-first so the cacheable byte-prefix is maximised across deploys, sessions, and projects
+- ⊗ MUST NOT place a per-session fragment (e.g. session timestamp) ahead of a per-project fragment (e.g. AGENTS.md) -- the per-session change would invalidate everything below it on every new session
+- ⊗ MUST NOT place a per-project fragment ahead of a per-deploy fragment (e.g. agent identity) -- the same inversion penalty applies across the deploy axis
+- ~ SHOULD measure cache hit rate per turn and per session as part of the LLM-specific observability surface (see `patterns/llm-app.md` `## LLM-specific observability`); a falling cache hit rate is the canonical drift signal that ordering or layering has regressed
+
+## Ephemeral injection -- rebuilt on every API call
+
+The ephemeral layer is everything the model needs *for this turn* that
+the model did not need on prior turns. It is injected as part of the
+per-turn user message (or as a turn-scoped system addendum where the
+provider supports it) and is never cached.
+
+Canonical content for the ephemeral layer:
+
+- **Current-turn context overlays** -- task-scoped instructions, role overlays (see #816), per-turn safety reminders
+- **Gateway-derived session context** -- request id, user id, locale, feature flags surfaced for this turn
+- **Later-turn memory recall** -- memory snippets surfaced *after* session start (the frozen-snapshot rule from #832 forbids editing the cached prefix's memory; recalls go here)
+- **Prefill messages** -- assistant-side prefills used to steer the next decode
+- **Current user input** -- the user's turn, wrapped in the trust-tier envelope from `patterns/llm-app.md` `## Prompt construction`
+- **Tool results from prior turns** -- `<tool_result>...</tool_result>` blocks injected as observations for the next decode
+
+- ! MUST rebuild the ephemeral layer on every API call from authoritative per-turn state -- never reuse a stale serialisation across turns
+- ! MUST inject later-turn memory recall into the **user message** (not the system prompt) -- writing recall into the system prompt forces a cache miss AND violates the frozen-snapshot rule from #832
+- ⊗ MUST NOT splice ephemeral content into the cached prefix at construction time as an optimisation -- the optimisation reverses on the second turn and gets strictly worse from there
+- ⊗ MUST NOT carry ephemeral fragments forward as cached state across turns -- a per-turn task instruction that becomes part of the prefix locks the agent into that instruction for the rest of the session
+- ~ SHOULD wrap ephemeral fragments in explicit delimiters (`<turn_context>`, `<recall>`, `<tool_result>`) so the model can be instructed to treat them as turn-scoped rather than session-scoped
+
+## Why this matters for directive
+
+Directive-built agents typically assemble their system prompt from
+multiple sources (AGENTS.md, USER.md, project-definition narratives,
+skill bodies, vBRIEF excerpts, memory snippets). Without an explicit
+layering contract:
+
+- Agent-written context-file content gets mixed into system-prompt fragments, fragmenting cache hits
+- Memory updates land in the system prompt mid-session, invalidating every cached byte after the insertion point
+- Per-turn metadata (timestamps, current task name, current vBRIEF being worked) gets templated into the system prompt instead of the user message
+- Token cost scales `O(N_turns × prompt_size)` instead of `O(prompt_size + N_turns × delta)` -- a 10x cost regression at 10 turns/session, 100x at 100
+
+This pattern is the structural fix. The frozen-memory-snapshot rule
+(#832) is the load-bearing consequence: memory that lives in the cached
+prefix MUST be frozen at session start; subsequent recall happens in
+the ephemeral layer.
+
+## Observability
+
+The cache-tier classification is invisible to standard request/response
+tracing -- a cache miss looks like a normal request, just slower and
+more expensive. The LLM-specific observability surface
+(`patterns/llm-app.md` `## LLM-specific observability`) is the canonical
+home for cache-tier telemetry; this pattern adds the cache-specific
+fields.
+
+- ! MUST log the cached-prefix hash on every session-start event so prefix drift between deploys, projects, or sessions is detectable post-hoc
+- ! MUST log cache hit rate per turn (provider-reported where available; derived from token counts otherwise) so layering regressions surface as a falling metric, not as a silent cost increase
+- ~ SHOULD log per-fragment layer classification (cached vs ephemeral) at construction time so post-hoc audits can see exactly which fragments lived in which layer
+- ~ SHOULD alert on a sustained cache hit rate drop -- a cache hit rate that falls without a deploy is the canonical signal that an ephemeral fragment leaked into the cached prefix
+- ⊗ MUST NOT log raw prompt bodies into general application logs (the `patterns/llm-app.md` audit-log-separation rule applies equally to cached-prefix bodies; the hash is queryable, the body lives in the audit log)
+
+## Anti-patterns
+
+- ⊗ Re-rendering the cached prefix on every API call (the canonical cache-miss footgun -- the prefix is supposed to be byte-identical across turns)
+- ⊗ Injecting current timestamp, current task, or current user message echo into the cached prefix (per-turn variability in a session-scoped layer)
+- ⊗ Editing the frozen memory snapshot mid-session (the #832 frozen-snapshot rule has the same root cause; this pattern names it)
+- ⊗ Placing per-session fragments (session timestamp) ahead of per-deploy fragments (agent identity) in the cached prefix (ordering inversion that invalidates the deploy axis)
+- ⊗ Storing ephemeral per-turn role overlays (#816) into the cached system prompt instead of the user message
+- ⊗ Treating prompt caching as a provider-side optimisation the application can ignore (it is a first-class application-side contract; the application controls every byte that determines the cache hit length)
+- ⊗ Reporting "the prompt fits the context window" as the success metric (the success metric is `cache_hit_rate × N_turns`, not `prompt_length < context_limit`)
+
+## Cross-references
+
+- `patterns/llm-app.md` -- the parent LLM application standards (#481); this file extends `## Prompt construction` and the `## LLM-specific observability` audit-log requirements with the cache-tier contract
+- `context/context.md` -- the **Write** strategy externalises ephemeral state to scratchpad files; the **Compress** strategy reduces per-turn token cost; both are operationalised here for the LLM-call boundary
+- #832 -- frozen-memory-snapshot rule (the load-bearing consequence of this pattern; memory in the cached prefix MUST be frozen at session start)
+- #816 -- role-as-overlay (roles are ephemeral, not cached; they live in the per-turn injection layer)
+- #788 -- token cost as design constraint (the parent framing this pattern enforces at the prompt-assembly layer)

package/patterns/role-as-overlay.md

@@ -0,0 +1,179 @@
+# Role as overlay (#816)
+
+Architectural standard for how persona and role instructions are applied
+to LLM calls in directive's skills, agents, and downstream consumers.
+Role instructions MUST be implemented as **call-scoped system-prompt
+overlays**, never injected into the persisted message history.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**Load when:** the project applies a persona, role, or stance to an LLM
+call (skill-defined reviewer / builder / summarizer roles, agent-level
+identities, per-call stance overrides) or designs a multi-turn agent
+that persists message history across turns.
+
+**Source material:** Flue SDK ([withastro/flue](https://github.com/withastro/flue))
+README -- "Role instructions are applied as call-scoped system prompt
+overlays, not injected into the persisted user message history."
+Precedence: call role > session role > agent role.
+
+**⚠️ See also**:
+- [./llm-app.md](./llm-app.md) -- the trust-tier framework this pattern reinforces (the system prompt is the trust boundary; user-tier messages are untrusted)
+- [../coding/security.md](../coding/security.md) -- `## Agent-Specific Threats` (prompt-injection isolation, internal-prompt non-exposure -- the security-side framing of the same boundary)
+- [./multi-agent.md](./multi-agent.md) -- sub-agent dispatch envelope (the orchestration analogue: per-dispatch role overlay, never aggregated into shared history)
+
+## The principle
+
+When a skill or agent applies a persona to an LLM call ("you are a
+security reviewer", "you are a senior engineer", "you are a concise
+summarizer"), that instruction is **configuration**, not **content**.
+It describes *how* to process the work, not *what* work happened.
+
+- ! MUST apply persona / role instructions as system-prompt overlays at the call boundary -- never as `user` or `assistant` messages in the persisted history
+- ! MUST treat the message history as the durable record of *what happened*: user turns, tool calls, tool results, assistant turns. Role instructions are not events; they are dispositions
+- ⊗ MUST NOT prepend a `user` message of the form `"You are a security reviewer. ..."` to the conversation array as a way to apply a role -- this is the canonical anti-pattern this rule eliminates
+- ⊗ MUST NOT prepend a synthetic `assistant` message of the form `"Understood, I am a security reviewer. ..."` either -- mirrored variant of the same anti-pattern
+- ! MUST keep the overlay **ephemeral**: it applies for the duration of the call and disappears; the next call's overlay is computed fresh from the precedence chain
+- ~ SHOULD render the effective system prompt (agent base + session overlay + call overlay) into a structured audit-log entry alongside the call, per [`patterns/llm-app.md`](./llm-app.md) `## LLM-specific observability` -- the overlay is a configuration artifact and is traced as one
+
+## Why this matters
+
+The failure mode is concrete and recurrent. An agent that injects role
+instructions as messages accumulates them across turns:
+
+```text path=null start=null
+# Anti-pattern: role-as-message
+messages = [
+  {"role": "user", "content": "You are a security reviewer. Review this code."},
+  {"role": "user", "content": "<the actual code>"},
+  {"role": "assistant", "content": "<the review>"},
+  {"role": "user", "content": "You are a security reviewer. Now check the tests."},
+  {"role": "user", "content": "<the tests>"},
+  ...
+]
+```
+
+Versus the correct shape:
+
+```text path=null start=null
+# Correct: role-as-overlay
+system  = "<agent base prompt> + <session role> + <call role: security reviewer>"
+messages = [
+  {"role": "user", "content": "Review this code."},
+  {"role": "user", "content": "<the actual code>"},
+  {"role": "assistant", "content": "<the review>"},
+  {"role": "user", "content": "Now check the tests."},
+  {"role": "user", "content": "<the tests>"},
+  ...
+]
+```
+
+Concrete consequences of the anti-pattern:
+
+- **History pollution.** A resuming agent (or a human reading the
+  transcript later) sees spurious `"you are a reviewer"` user turns
+  interleaved with real work. The record is no longer a faithful
+  description of the conversation -- it conflates *who said what* with
+  *how the model was configured*. Forensic review on a faulty output
+  cannot distinguish operator intent from runtime configuration.
+- **Retrieval corruption.** If the message history feeds a downstream
+  retrieval index (chat search, conversation summarization, vBRIEF
+  ingestion, RAG re-use of prior turns), the role-injection turns
+  become indexable content. A search for "security reviewer" then
+  surfaces configuration noise instead of actual reviewer findings.
+  This is the persistence-layer analogue of the RAG-poisoning failure
+  the [`patterns/llm-app.md`](./llm-app.md) `## RAG and retrieval`
+  section warns against.
+- **Context rot acceleration.** Role-injection turns count against the
+  context window every turn. Long sessions burn token budget on
+  repeated `"you are a reviewer"` strings that contribute zero
+  information beyond the first occurrence -- and the model's attention
+  drifts under the accumulated repetition. This is a known structural
+  cause of context degradation (#674).
+- **False memory propagation.** When the polluted history is summarized
+  or compacted, the summarizer treats role-injection turns as real
+  content and may propagate the persona claim into the summary
+  ("the user repeatedly emphasized that the model is a security
+  reviewer"). The persona then enters a parallel persistence channel
+  with no provenance back to the actual configuration source. This is
+  the structural origin of #479 (false memory propagation in vBRIEF
+  trust levels).
+- **Resumption breakage.** A session resumed from polluted history
+  re-applies the historical role-injection turns AND the fresh
+  overlay, doubling the role assertion. Subtle behavioral drift
+  follows: the model sees two `"you are a reviewer"` signals with
+  potentially different framings and resolves the conflict
+  unpredictably.
+
+The overlay shape avoids all five failure modes by construction. The
+history records work; the overlay records configuration; the two never
+mix.
+
+## Precedence
+
+When multiple roles apply, resolve them in this order, highest to
+lowest:
+
+```text path=null start=null
+call role        <- HIGHEST (per-invocation override, the most specific intent)
+  |
+session role     <- session-scoped default (e.g. "this whole review pass is a security audit")
+  |
+agent role       <- LOWEST (the agent's baseline identity, e.g. "you are a Deft Directive skill executor")
+```
+
+- ! MUST resolve role precedence call > session > agent at every LLM call. Lower-tier roles are defaults; higher-tier roles override without modifying the lower-tier's record
+- ! MUST compose the effective system prompt as `agent_base + session_overlay + call_overlay`, in that exact order, so the call overlay is the last instruction the model reads
+- ⊗ MUST NOT mutate the agent or session role from a call-level overlay -- the call overlay is ephemeral by definition; persisting it changes the precedence semantics into a "last call wins" model that is silently history-dependent
+- ⊗ MUST NOT silently drop a higher-tier overlay because a lower-tier role disagrees -- the higher-tier value is authoritative; surface the conflict in the audit log if useful for debugging
+- ~ SHOULD log the resolved precedence chain alongside each call: `(agent="deft-build", session=null, call="security-reviewer") -> effective="security-reviewer"`. This makes the overlay's effect on a given call queryable post-hoc
+
+## Implementation contract for skills and agents
+
+Directive's skills implicitly carry roles -- `deft-directive-review-cycle`
+is a reviewer, `deft-directive-build` is a builder, `deft-directive-pre-pr`
+is a quality-checker. Each skill's role MUST be applied as an overlay
+when the skill dispatches an LLM call (or instructs a sub-agent to do
+so), never as an injected message turn.
+
+- ! Skills that apply a role to an LLM call MUST surface the role as a system-prompt overlay parameter (or the equivalent provider-supported field) at the call boundary
+- ! Skills that dispatch sub-agents MUST pass the role through the dispatch envelope as a configuration field (e.g. `role: "security-reviewer"`), not as a prepended user message in the sub-agent's seed history
+- ⊗ Skills MUST NOT generate role-injection prose into the work product (PR body, commit message, scope vBRIEF narrative, lessons.md entry) -- the role is internal configuration, not output content
+- ! When a sub-agent receives a role via the dispatch envelope, it MUST treat the role as authoritative call-scoped configuration; it MUST NOT persist the role string into its own conversation history as a synthetic user turn
+- ~ Skill authors SHOULD document the skill's default role (agent-tier) in the SKILL.md frontmatter or a dedicated `## Role` section so consumers can override it consciously at session or call tier
+- ? Skills MAY accept a `--role` override at invocation time; if accepted, the override resolves at call tier per the precedence chain above
+
+### Provider mapping
+
+| Provider                  | System overlay surface                                                                |
+|---------------------------|---------------------------------------------------------------------------------------|
+| Anthropic Messages API    | `system` parameter on the request (string or content-block array)                     |
+| OpenAI Chat Completions   | `messages[0]` with `role: "system"` -- one entry, never duplicated across the array   |
+| OpenAI Responses API      | `instructions` parameter on the request                                               |
+| Google Gemini             | `system_instruction` field on the request                                             |
+| Local / open-source LLMs  | The provider-specific system prompt slot in the request schema                        |
+
+- ! MUST use the provider's native system-prompt surface for the overlay -- do not fall back to a user-tier message because the provider's system surface "is harder to template"; the surface IS the trust boundary
+- ⊗ MUST NOT emit more than one system-role entry in providers that expect a single system slot (e.g. OpenAI Chat Completions) -- compose the overlay into a single string before the call
+- ~ When the provider supports structured system content (Anthropic content-block array), SHOULD render `agent_base` / `session_overlay` / `call_overlay` as separate blocks so the audit log can split them; the resulting effective prompt is still call-scoped and ephemeral
+
+## Anti-patterns
+
+- ⊗ Prepending a `user` turn `"You are a <role>. <task>"` instead of using the system overlay surface -- the canonical anti-pattern this rule eliminates
+- ⊗ Prepending a synthetic `assistant` turn `"Understood, I am a <role>."` to acknowledge the role -- mirrored variant of the same anti-pattern
+- ⊗ Embedding role instructions in the first real user turn (`"As a security reviewer, please review the following: ..."`) -- still pollutes the history; the model and any downstream consumer see the role as user-tier content
+- ⊗ Persisting the call-tier overlay back into the agent or session role -- collapses the precedence chain into silent history-dependent behavior
+- ⊗ Aggregating role instructions across turns ("you are a reviewer", "you are also concise", "you are also formal") via repeated user-turn injection -- compose the overlay at call time instead, so the model sees one coherent role specification per call
+- ⊗ Leaking the overlay into the work product (PR body / commit message / scope vBRIEF narrative) -- the role is internal configuration; the work product describes outcomes, not the model's stance
+- ⊗ Treating a sub-agent's seed history as a place to "configure its persona" -- pass the role through the dispatch envelope as configuration and let the sub-agent apply it as its own call-tier overlay
+
+## Cross-references
+
+- #674 -- context rot (role-injection-as-messages is a documented structural contributor)
+- #479 -- false memory propagation (the persistence-layer analogue of role pollution when polluted history is summarized)
+- #808 -- share state, isolate cognition (the orchestration cousin of this rule)
+- #662 -- context degradation recovery
+- [`patterns/llm-app.md`](./llm-app.md) `## Prompt construction` and `## Trust tiers` -- the system prompt is the trust boundary this overlay parameter writes to; user-tier messages are explicitly untrusted, so role-as-user-message inverts the trust contract
+- [`coding/security.md`](../coding/security.md) `## Agent-Specific Threats` -- prompt-injection isolation and the rule against exposing internal system prompts to untrusted surfaces (the security-side framing of the same boundary)
+- [`patterns/multi-agent.md`](./multi-agent.md) -- multi-agent dispatch envelope; role overlays travel as dispatch-time configuration, not as injected history
+- Flue SDK README -- source attribution for the call > session > agent precedence model