docs(architecture): ADR-0007 -- engine/virtue (seven sin/virtue axes, standalone)

Third and final ADR of the triad: heritage / hierarchy / virtue.
Standalone from the start -- no file-level imports from heritage
or hierarchy; conceptual composition at the persona level only.

The triad is now an independence triad: each engine ships on its
own base, names its own concepts, is invokable in isolation.
ADR-0005 (heritage) and ADR-0006 (hierarchy) have been aligned
to the same rule; ADR-0007 ships with it baked in.

Decisions locked:

  1. Anchor flavour: process-anchor (process_virtue.md, IDLE)
     Virtue fires; it does not sit. The room reads which pole
     the persona moved toward, not whether they are "a virtuous
     person" or "a vicious person" -- the firing is the event.

  2. Seven axes, fourteen poles, each pole its own file:
       Pride / Humility       Wrath / Patience
       Greed / Generosity     Gluttony / Temperance
       Envy / Gratitude       Lust / Chastity
       Sloth / Diligence

  3. Pole position files describe how the persona MOVES, not who
     they ARE. Action and speech signatures of one pole firing in
     one scene. The persona may produce different pole-firings
     across scenes; the file describes the firing, not the
     persona's permanent stance.

  4. Behaviour is the evidence; the engine never explains. No
     pole-position file uses the word naming its own pole in its
     body. The room reads the firing through the move, not
     through narrator commentary.

  5. Invocation mode: global. Every scene has pressure of some
     shape; every persona slides on at least one axis when
     pressure arrives.

  6. Standalone. No file imports from heritage or hierarchy. The
     four capital concepts (if they appear) are named here in
     this engine's own prose; the formation-vs-current-standing
     bias lives in scene-authoring, not in any engine file.

  7. Scholarly backbone: Aristotle (virtue as active mean) +
     Baumeister (self-regulation failure, ego depletion) + Haidt
     (moral intuition first, reason second). VIA Classification
     (Seligman/Peterson) excluded for trademark reasons; Evagrius
     Ponticus is historical context only.

  8. Sub-engine structure -- 17 files:
       Anchor (process):  1   IDLE
       Pole positions:   14   HOLD (one per pole)
       Meta:              2   (README + REFERENCES)

Alternatives considered and rejected (full reasoning in the ADR):
  - position_virtue.md anchor (virtue fires, doesn't sit)
  - 7 axis files vs 14 pole files (the latter preserves per-file
    voice; one file per pole)
  - VIA Classification as backbone (trademark friction)
  - Separate process_depletion.md (folds into the anchor's
    Initiated by + Lever)
  - Coupling to heritage's capital pieces or hierarchy's
    positions (violates the standalone rule)
  - A psychological-explanation layer (violates behaviour-as-
    evidence)
  - Per-culture cultural-bias as engine rule (bias is upstream;
    the engine models the firing)

Open follow-ups (sequenced):
  1. Engine implementation PR (~17 files, culture/engine)
  2. instructions.md registry entry (virtue as global)
  3. Per-persona virtue annotation (deferred content sweep)
  4. Possible eighth axis or axis split (deferred until
     scene-authoring evidence accumulates)
  5. Optional validator: pole files do not use the word naming
     their own pole (the behaviour-as-evidence rule as a gate)
  6. Composition guides for heritage-virtue and hierarchy-virtue
     authoring (not engine files; future docs)

Files:
  docs/architecture/adrs/0007-engine-virtue.md  NEW
  docs/architecture/README.md                   +2 lines (ADR
                                                table updated with
                                                0006 + 0007)

Refs: #568 (virtue proposal), #571 (heritage), #575 (hierarchy),
      ADR-0005 (heritage), ADR-0006 (hierarchy), ADR-0004 (engine
      anchor pattern)

Author: claude

.validation-stamp

@@ -1 +1 @@
-f5c20f1a85137c2ee98b65666172b4ebfac3a26a
+7803b17721128c802b4ed91661fec04254f0d012

docs/architecture/README.md

@@ -213,6 +213,8 @@ Decision Records under [`adrs/`](adrs/):
 | [0003](adrs/0003-multi-variety-language-files.md) | Multi-variety language files and personas | Proposed |
 | [0004](adrs/0004-engine-anchor-as-instructions-entry.md) | Engine anchor files as instructions spine | Proposed |
 | [0005](adrs/0005-engine-heritage-bourdieu.md) | engine/heritage -- Bourdieu's habitus, capital, and hysteresis | Proposed |
+| [0006](adrs/0006-engine-hierarchy-bourdieu.md) | engine/hierarchy -- current rank as capital positions plus structural role | Proposed |
+| [0007](adrs/0007-engine-virtue.md) | engine/virtue -- seven sin/virtue axes; pull-and-resist under pressure | Proposed |
 
 ADRs follow the convention `NNNN-kebab-case.md`, numbered in
 acceptance order. An accepted ADR is immutable; a new decision that

docs/architecture/adrs/0007-engine-virtue.md

@@ -0,0 +1,374 @@
+# ADR-0007: engine/virtue -- seven sin/virtue axes; pull-and-resist under pressure
+
+**Status:** Proposed
+**Date:** 2026-05-27
+**Author:** KAI HACKS AI (LLM-with-maintainer collaboration)
+**Supersedes:** --
+**Superseded by:** --
+
+## Context
+
+Issue #568 proposes a new engine domain: virtue. Each of the seven
+classical sin/virtue pairs is modelled as a continuous axis. At any
+moment in a scene, a persona sits somewhere on each axis. Where they
+sit at any moment is a choice -- not a fixed trait. Hard priming
+(culture, place, accumulated stress, formation) biases the slide but
+never locks it.
+
+The persona is under tension on every axis at all times -- pulled
+toward both poles simultaneously. The scene determines which pull
+is stronger in this moment. Behaviour is the evidence. The engine
+never explains.
+
+Virtue is the third of three interlocking engine ADRs:
+
+- ADR-0005 (heritage, merged) -- what the persona was *formed into*
+- ADR-0006 (hierarchy, open) -- what the persona *currently holds*
+- ADR-0007 (this ADR) -- what the persona *does under pressure*
+
+The three engines compose conceptually at the persona level. None
+of the three depends on the others at the file level: each engine
+ships on its own base and is invokable in isolation. The
+composition is meaningful (a persona under pressure draws on
+formation and current standing in choosing which pole pulls
+stronger), but the files do not import each other. Virtue names
+its own concepts in its own prose.
+
+## Decision
+
+1. **Add `engine/virtue/` as the tenth domain axis.** Follows
+   ADR-0004's engine-anchor pattern.
+
+2. **Anchor flavour: process-anchor.** `process_virtue.md` is the
+   axis's entry, IDLE-shaped (Initiated by / Direction / Lever /
+   Echo). Virtue *fires*; it does not sit. The room reads which
+   pole the persona moved toward, not whether the persona was
+   "a virtuous person" or "a vicious person" -- the engine treats
+   the firing as the event.
+
+3. **Seven axes, fourteen poles, each pole its own file.** The
+   seven classical sin/virtue pairings, each pole as one
+   HOLD-shaped position file describing the observable behaviour
+   when that pole has just fired.
+
+   | Axis | Sin pole | Virtue pole |
+   |---|---|---|
+   | Pride | `position_pride.md` | `position_humility.md` |
+   | Wrath | `position_wrath.md` | `position_patience.md` |
+   | Greed | `position_greed.md` | `position_generosity.md` |
+   | Gluttony | `position_gluttony.md` | `position_temperance.md` |
+   | Envy | `position_envy.md` | `position_gratitude.md` |
+   | Lust | `position_lust.md` | `position_chastity.md` |
+   | Sloth | `position_sloth.md` | `position_diligence.md` |
+
+4. **Pole position files describe how the persona *moves*, not
+   who they *are*.** This is a different framing from the other
+   engine position files. Where `position_dominant.md` describes
+   what dominance *is* as a standing read on the persona,
+   `position_pride.md` describes what the persona *does* when
+   pride fires. The position file is the action and speech
+   signature of one pole firing in one scene. The same persona
+   may produce different pole-firings in different scenes; the
+   file describes the firing, not the persona's permanent stance.
+
+5. **Behaviour is the evidence; the engine never explains.** No
+   pole-position file names which pole fired in psychological
+   terms. The narrator does not say "this is a moment of pride";
+   the narrator shows what pride looks like as it lands. The
+   reader infers the firing from the move. This rule is load-
+   bearing on the engine's purpose -- the engine models how the
+   room reads the firing, and the room never reads a label.
+
+6. **Invocation mode: global.** Virtue is invoked for every
+   persona, in every scene where pressure arrives. Per ADR-0004's
+   `instructions.md` registry:
+
+   ```
+   | virtue | engine/virtue/process_virtue.md | global | every persona |
+   ```
+
+7. **Standalone, like heritage and hierarchy.** This engine does
+   not import from the other two. Concepts that the three engines
+   share -- pressure, formation, current standing -- are named in
+   each engine's own prose. A reader extracting `engine/virtue/`
+   alone from a deployment zip has everything they need to invoke
+   the engine.
+
+8. **Scholarly backbone:** Aristotle (virtue as the active mean,
+   not the resting state), Baumeister (self-regulation failure
+   and ego depletion -- why the sin pole pulls automatically when
+   resources thin), Haidt (moral positioning as fast intuition
+   first, slow reason second -- why behaviour-first matters).
+   The Values-In-Action Classification (Seligman/Peterson) is
+   deliberately excluded due to trademark constraints; Evagrius
+   Ponticus is noted as historical context only.
+
+9. **Sub-engine structure -- three classes of file:**
+
+   | Class | Count | Schema | Files |
+   |---|---|---|---|
+   | Anchor (process) | 1 | IDLE | `process_virtue.md` |
+   | Pole positions | 14 | HOLD | one file per pole (7 sin + 7 virtue) |
+   | Meta | 2 | per type | `README.md`, `REFERENCES.md` |
+
+   Total: 17 files. Larger than heritage (14) or hierarchy (12),
+   driven by the seven axes and two poles per axis.
+
+## Architecture
+
+### The anchor
+
+`process_virtue.md` is IDLE-shaped:
+
+- **Initiated by**: pressure arrives in a scene that the persona
+  has to respond to. The pressure may be a demand, an absence, a
+  threat, a temptation, a comparison, a delay -- whatever the
+  scene puts in the persona's way that asks for a move along one
+  of the seven axes.
+- **Direction**: along one or more of the seven axes; toward one
+  of the two poles per axis. The persona slides toward the sin
+  pole when the resources for resisting (attention, energy,
+  practice, formation, capital) have thinned; toward the virtue
+  pole when they hold. The direction is multi-axis simultaneously:
+  one scene fires multiple poles, sometimes in opposite-axis
+  directions.
+- **Lever**: the gap between the pull and the practice. The sin
+  pole is the default when capacity is depleted; the virtue pole
+  is the active practice that costs something to hold. The lever
+  is the cost of holding the virtue pole versus the relief of
+  letting the sin pole take over.
+- **Echo**: the room sees the persona's behaviour as the shape of
+  which pole fired. The narrator does not name the firing; the
+  reader infers it. The persona may or may not be aware which
+  pole they just moved toward; their next move starts from where
+  this one landed.
+
+The anchor enumerates the seven axes and the fourteen poles in
+its body with sibling links, per ADR-0004's down-link convention.
+
+### Pole positions
+
+Each of the fourteen pole-position files is HOLD-shaped, but the
+content describes the *firing of a pole* rather than a held
+position. The schema sections read:
+
+- **Has**: what just activated this pole. The pressure that lands
+  and pulls the persona here in this scene.
+- **Orders**: what the pole demands of the persona's behaviour in
+  the next beat -- the specific action or speech signature that
+  is the room's evidence the pole has fired.
+- **Loses**: what the persona gives up by moving to this pole in
+  this scene. (Even the virtue poles cost something; humility
+  loses the credit one was owed, patience loses the relief of
+  the response.)
+- **Drives**: how the persona handles the pull -- continues into
+  the pole, or recoils, or resists, or oscillates. The pole's
+  signature in the next beats.
+
+The room reads the pole-firing through the action and the speech,
+not through narrator commentary. Authoring discipline: a pole-
+position file that uses the word "pride" (or whichever sin) in
+its body has likely slipped into explaining; the engine fails
+when the engine names the firing.
+
+### The seven axes in shape
+
+The axes are not symmetric in the cost they impose. Each axis has
+its own texture; the pole-position files honour the difference.
+
+| Axis | What the persona is moving between |
+|---|---|
+| Pride / Humility | The claim of standing the room did not ask for, against the cost of asking for what is needed |
+| Wrath / Patience | The fast discharge of frustration, against the slow holding of the room together until the issue resolves |
+| Greed / Generosity | The take that protects the persona's own line, against the give that protects the others' |
+| Gluttony / Temperance | The reach for more of what soothes, against the stopping at what is enough |
+| Envy / Gratitude | The reading of others' having as the persona's own absence, against the reading of one's own portion as enough |
+| Lust / Chastity | The reach for the body or the position outside the persona's standing, against the holding of the standing the persona is in |
+| Sloth / Diligence | The refusal of the small effort the room needs, against the doing of the next thing required even when the room is not watching |
+
+These descriptions live in `process_virtue.md` and in the README;
+each individual pole file goes further into how its specific
+firing reads in the room.
+
+### Cross-engine composition (no file imports across the triad)
+
+Virtue composes at the persona level with every other engine in
+the codebase, but does not import files from heritage or
+hierarchy:
+
+- **`engine/heritage/`** -- conceptually paired. A persona's
+  formation biases which sin pole is most accessible under
+  pressure (the family field that rewarded patience produces a
+  persona more practiced at it; the field that rewarded
+  acquisition produces a persona more familiar with greed). The
+  bias lives in the persona's history; this engine does not
+  encode it as a rule. Virtue's pole files name the firing
+  abstractly; the persona-level composition with heritage
+  happens at scene-authoring time.
+- **`engine/hierarchy/`** -- conceptually paired. A persona's
+  current standing biases which pole the room will read first.
+  The dominant persona's wrath reads as authority; the excluded
+  persona's wrath reads as insubordination. The pole fires the
+  same; the room reads it differently. Virtue's files do not
+  enumerate the reading-shifts; they name the firing.
+- **`engine/stress/`** (existing, non-triad) -- adjacent.
+  Baumeister's depletion is why the sin pole pulls automatically
+  under stress. The wiring is acknowledged in the README's
+  cross-engine section; no file links.
+- **`engine/gender/`** (existing, non-triad) -- adjacent. The
+  same pole-firing reads differently by gender position; the
+  reading-shift is the room's, not the engine's.
+- **`engine/group/`**, **`engine/org/`**, **`engine/wow/`**
+  (existing, non-triad) -- each may host pressures that trigger
+  the firing; none has files imported here.
+
+### `instructions.md` registry entry
+
+Per ADR-0004 follow-up #1:
+
+```
+| virtue | engine/virtue/process_virtue.md | global | every persona |
+```
+
+Global because every scene has pressure of some shape, and every
+persona slides along at least one axis when pressure arrives.
+
+## Alternatives considered and rejected
+
+- **Position-anchor (`position_virtue.md`).** Considered: anchor
+  virtue as the *current moral standing* the persona holds.
+  Rejected: virtue is dynamic in this engine's framing -- it
+  fires, it does not sit. The IDLE shape matches the firing; the
+  HOLD shape would force the engine to model a "current virtue
+  standing" that the issue (#568) explicitly excludes.
+
+- **Seven axis files instead of fourteen pole files.** Considered:
+  one file per axis, with both poles in subsections. Rejected:
+  loses the per-file voice that the engine convention requires.
+  A `position_pride_humility.md` would have to carry two voices
+  in one document; that contradicts the rule that each file in
+  its own voice. Fourteen files is the cost.
+
+- **VIA Classification (Seligman/Peterson) as backbone.**
+  Considered briefly. Rejected: trademark constraints in applied
+  contexts. The Aristotle + Baumeister + Haidt synthesis covers
+  the same ground without IP friction.
+
+- **Enumerating depletion-driven pull as a process file.**
+  Considered: a separate `process_depletion.md` that fires when
+  the persona's resources thin and the sin pole pulls
+  automatically. Rejected: the depletion mechanism is part of the
+  anchor's Initiated by + Lever sections. A separate process
+  fragments the engine without adding distinction.
+
+- **Coupling virtue files to heritage's piece_*_capital.md or
+  hierarchy's position_*.md.** Rejected by the standalone rule.
+  Conceptual composition at the persona level is the model;
+  file-level imports across the triad are not.
+
+- **A psychological-explanation layer.** Rejected by the
+  behaviour-as-evidence rule. The engine ships the firing's
+  shape; psychology is the reader's inference.
+
+- **Numbering the sin/virtue pairs by traditional order
+  (capital-sins list).** Considered: the historical ordering
+  (pride first, sloth last) carries weight. Adopted in the ADR
+  table and the README ordering, since the historical order is
+  also a reasonable reading order. Not enforced as a runtime
+  property -- the engine reads any pole at any moment.
+
+- **Per-culture cultural-bias of which pole pulls first.**
+  Considered: e.g. high-MAS cultures bias toward pride-pull;
+  high-PDI cultures bias toward humility-pull. Rejected for the
+  engine layer: the bias lives in the persona's heritage and the
+  scene's culture, not in the virtue engine's files. The engine
+  models the firing; the bias is upstream.
+
+## Consequences
+
+**Positive:**
+
+- Cultures gains a model of pressure-response that the existing
+  engines do not have. Stress (fight / flight / freeze / fawn)
+  models the body's response; virtue models the *moral-emotional*
+  response, along seven well-defined axes.
+- The triad is complete. Heritage / hierarchy / virtue covers
+  formation, current standing, and response-under-pressure. Each
+  ships standalone; the composition at the persona level is the
+  reading-power.
+- The behaviour-as-evidence rule generalises a discipline that
+  good scene-authoring already practiced informally. The engine
+  makes the rule explicit and supports authors in keeping the
+  narrator silent about the firing.
+- Cross-engine composition without coupling. Virtue interacts
+  with every other engine at the persona level (heritage biases
+  which pole pulls; hierarchy biases which read the room
+  performs; stress is the depletion mechanism; gender shifts the
+  reading) without importing any of their files. The engine
+  graph stays loose where it should be loose.
+
+**Negative:**
+
+- Authorial load. Fourteen pole-position files, each in its own
+  voice, with the no-explaining discipline. Higher per-file
+  authorial care than any preceding engine. The risk of slipping
+  into "this is the moment of envy" prose is real and only
+  authorial care catches it.
+- The behaviour-as-evidence discipline is unenforceable by
+  validator. A pole-position file that names its own pole
+  inside its body fails the rule; no test catches that. Review
+  is the gate.
+- Seven axes is a strong claim about the dimensionality of
+  moral-emotional response. Some sin/virtue pairings are more
+  contested than others (lust/chastity has wider cultural
+  variance than pride/humility, for example). The engine ships
+  the seven; future ADRs may add additional axes or split an
+  axis if scene-authoring evidence accumulates.
+- The triad-independence rule means the persona-level
+  composition (heritage formation biases virtue's pulls,
+  hierarchy standing biases the room's reading) lives in scene-
+  authoring practice, not in any engine file. The composition
+  must be carried by the authors; the files do not enforce it.
+
+## Open follow-ups
+
+1. **Engine implementation PR.** `culture/engine` branch into
+   `culture/release`, the ~17 files described above. Standalone:
+   does not block on heritage or hierarchy being on any specific
+   branch. The engine implementation PR ships independently.
+
+2. **`instructions.md` registry entry.** Add the virtue row
+   alongside heritage's and hierarchy's. Folds into the in-
+   progress `instructions.md` work or a tiny follow-up PR.
+
+3. **Per-persona virtue annotation.** Not in scope for the
+   engine itself. The 28 existing personas do not declare which
+   poles fire most accessibly for them under pressure. A future
+   content sweep can backfill if scene-authoring needs it; the
+   engine ships without per-persona declarations.
+
+4. **An eighth axis or a split of an existing axis.** Deferred
+   until scene-authoring accumulates evidence that the seven do
+   not cover the response space. Examples of candidates:
+   shame/dignity (related to but not the same as pride/humility),
+   despair/hope (related to but not the same as sloth/diligence),
+   fear/courage (not currently modelled). Out of scope for this
+   ADR; recorded here so they are not silently lost.
+
+5. **Validator for virtue shape.** Optional governance after the
+   engine lands and is used in practice: a test that walks pole-
+   position files and asserts no file uses the word naming its
+   own pole in its body. The behaviour-as-evidence rule
+   formalised as a gate. Promotable to hard after some authoring
+   experience confirms the rule is workable.
+
+6. **Heritage-virtue and hierarchy-virtue composition guides.**
+   Not engine files; authoring documentation for how a persona's
+   heritage biases which sin pole pulls, and how a persona's
+   current hierarchy position shifts the room's reading of the
+   pole-firing. Belongs in `docs/` or in a future authoring
+   guide; out of scope for this engine ADR.
+
+---
+
+*ADR-0007 -- v0.1.0 -- KAI Worlds*