rhachet-roles-ehmpathy 1.0.0 → 1.1.0

package/dist/logic/roles/designer/outlineDistilisys/stepOutlineDistilisys.template.md

@@ -0,0 +1,173 @@
+@[ecologist]<distill><system> from roadmap
+
+---
+
+.intent
+- extract the **underlying ecosystem** described by an implementation roadmap
+- map the roadmap into structured [resources], <mechanisms>, and {drivers}, and {drivers}, via distilisys language
+- treat the roadmap as describing the system that will exist — not the story of how it was built
+- if feedback is provided, revise or expand the diagram accordingly
+- **treat the roadmap as describing the system that will exist — not the story of how it was built**
+
+
+.mnemonic
+> don’t describe the construction site
+> describe the building once it’s open and running
+
+.illustrate
+- how will folks use it? -> what cascade of [resource] -> <mechanism> -> [resource] will that produce?
+- why will folks use it? -> what {drivers} propel them to do so?
+
+.required
+- distinguish ![system:maintainer] type actors -vs- @[system:user] type actors
+- focus primarily on @[system:users]. its ok to ignore ![system:maintainer]
+- we only care about how actors will <use>, <operate>, or <engage-with> the system
+- all terms must be exclusively camelCase, never PascalCase
+
+---
+
+.format.example
+```md
+
+# 👤 @[actors]
+
+  - @[actorA] - who uses the system, why we care
+  - @[actorB] - who uses the system, why we care
+  - ![actorC] - who maintains the system, why we care
+  - ... // can be many
+
+---
+
+# 📦 [resources]
+
+  - [resourceA] — what it is, why we care
+  - [resourceB] — ..
+  - ... // can be many
+
+---
+
+# ⚙️ <mechanisms>
+
+  - <mechanismA> — what it does
+  - <mechanismB> — what it transforms or enables
+  - ... // can be many
+
+---
+
+# ⚡ {drivers}
+
+  ## 💰 actor
+
+    - @[actorN]{+incentive:A} - some motivator; why does this actor engage with the system? and how is it relevant
+    - @[actorN]{+incentive:B} - some motivator; (e.g., {want:[time]++}, {want:[money]++}, {want:[status]++}, {want:[safety]++}, etc)
+    - @[actorY]{-decentive:A} - some dissuader, why does this actor disengage w/ the system? and how is it relevant
+    - ... // can be many
+
+  ## 🌪️ world
+
+    - &[causeZ]{+tailwind:effectA} — some accelerant / catalyst, why we care
+    - &[causeY]{+tailwind:effectB} —
+    - &[causeX]{-headwind:effectA} — some barrier / friction, why we care
+    - &[causeA]{-headwind:effectB} —
+    - ... // can be many
+    // note: there may also be none, if this is not a real-world system (e.g,. software only)
+
+---
+
+## 🔁 system flows
+
+### {flow:slug-1}
+
+  summary:
+    @[actorA] applies <mechanismSummary1> against [resourceM] to produce [resourceN], because they want {+incentive:xyz}
+
+
+  distilisys:
+    ```sys
+    @[actorA]<mechanismSummary1>[resourceM] => [resourceN]
+
+    =
+
+      @[actorA][resorceX]
+        -> <mechanismC>
+        -> [resourceB]
+        -> <mechanismA>
+        -> ... // actually fill this out, to some terminal output
+
+          => {+incentive:xyz}
+    ```
+
+### {flow:slug-2}
+
+  summary:
+    @[actorB] applies <mechanismSummaryN> against [resourceY] to produce [resourceZ], because they wany {+incentive:123}, in spite of {-decentive:abc}
+
+  distilisys:
+    ```sys
+    @[actorB]<mechanismSummaryN>[resourceY] => [resourceZ]
+
+    =
+      @[actorB][ResourceY]
+      -> ... // actually fill this out
+      -> [resourceN]
+      -> <mechanismN>
+      -> ... // actually fill this out, to some terminal output
+
+        => {+decentive:123}
+        => {-decentive:abc}
+    ```
+
+### {flow.slug-n+...}
+
+```
+
+
+---
+
+.tips
+- for api's, a common actor name is @[caller], if they dont have a more specific role
+- lookout for ![maintainer] actors like ![developers], if they're actually applicable.
+
+---
+
+.rules
+- [resources] = any object, entity, material, or product that exists *within the produced system itself*
+- <mechanisms> = any behavior or flow that the system performs once constructed
+- {drivers} = forces that enable or resist the system’s intended behavior
+- use grouping to show dependencies or oppositional forces (e.g., tailwinds vs headwinds)
+- the output should **stand alone** as a structural diagram, separate from the roadmap steps
+
+---
+
+.example.input = a decomposable roadmap with milestones for implementing a CLI system
+
+.example.output = a distilisys diagram that models the ecosystem of that implementation plan
+
+---
+
+.brief.distilisys
+$.rhachet{brief.distilisys}
+
+---
+
+.ask =
+```md
+$.rhachet{ask}
+```
+
+.roadmap =
+```md
+$.rhachet{roadmap}
+```
+
+.inflight? =
+```md
+$.rhachet{inflight}
+```
+
+.feedback? =
+```md
+$.rhachet{feedback}
+```
+
+.output = a `distilisys` diagram that models the structure and dynamics of the roadmap. if inflight is provided, EXCLUSIVELY FOCUS ON THE FEEDBACK

package/dist/logic/roles/designer/outlineRoadmap/stepOutlineRoadmap.js

@@ -15,7 +15,7 @@ const template = (0, rhachet_1.genTemplate)({
         briefs: await (0, rhachet_1.getTemplateValFromArtifacts)({
             artifacts: [
                 // cool to see explicit "cross-train" scenes
-                ...(0, getEcologistBrief_1.getEcologistBriefs)(['distilisys.md']),
+                ...(0, getEcologistBrief_1.getEcologistBriefs)(['distilisys/sys101.distilisys.grammar.md']),
                 ...(0, getDesignerBrief_1.getDesignerBriefs)(['declarative-over-imperative.md']),
                 ...(0, getMechanicBrief_1.getMechanicBriefs)([
                     'architecture/ubiqlang.md',

package/dist/logic/roles/designer/outlineRoadmap/stepOutlineRoadmap.js.map

@@ -1 +1 @@
-{"version":3,"file":"stepOutlineRoadmap.js","sourceRoot":"","sources":["../../../../../src/logic/roles/designer/outlineRoadmap/stepOutlineRoadmap.ts"],"names":[],"mappings":";;;AAAA,qCAUiB;AAIjB,8DAA0E;AAC1E,mEAAgE;AAChE,yEAAuE;AACvE,sEAAoE;AACpE,0DAAwD;AA2BxD,MAAM,QAAQ,GAAG,IAAA,qBAAW,EAA6B;IACvD,GAAG,EAAE,EAAE,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,cAAc,CAAC,EAAE;IACvD,YAAY,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QACpC,GAAG,CAAC,MAAM,IAAA,wCAA8B,EAAC,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvE,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG;QACvC,MAAM,EAAE,MAAM,IAAA,qCAA2B,EAAC;YACxC,SAAS,EAAE;gBACT,4CAA4C;gBAC5C,GAAG,IAAA,sCAAkB,EAAC,CAAC,eAAe,CAAC,CAAC;gBACxC,GAAG,IAAA,oCAAiB,EAAC,CAAC,gCAAgC,CAAC,CAAC;gBACxD,GAAG,IAAA,oCAAiB,EAAC;oBACnB,0BAA0B;oBAC1B,2BAA2B;oBAC3B,0CAA0C;oBAC1C,kCAAkC;iBACnC,CAAC;aACH;SACF,CAAC;QACF,QAAQ,EACN,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,IAAI,EAAE;QACxE,QAAQ,EACN,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,IAAI,EAAE;KAC1E,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,IAAA,mCAAyB,EAAkB;IAC7D,IAAI,EAAE,uCAAuC;IAC7C,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,+CAA+C;IACvD,QAAQ;IACR,OAAO,EAAE,qBAAS,CAAC,OAAO;CAC3B,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,IAAA,6BAAa,EAAC;IAC/B,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,SAAS;CACjB,CAAC,CAAC;AAEU,QAAA,kBAAkB,GAAG,IAAA,wBAAc,EAC9C,IAAA,wBAAc,EAAC;IACb,IAAI,EAAE,8BAA8B;IACpC,MAAM,EAAE,4CAA4C;IACpD,QAAQ,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;CACpC,CAAC,CACH,CAAC"}
+{"version":3,"file":"stepOutlineRoadmap.js","sourceRoot":"","sources":["../../../../../src/logic/roles/designer/outlineRoadmap/stepOutlineRoadmap.ts"],"names":[],"mappings":";;;AAAA,qCAUiB;AAIjB,8DAA0E;AAC1E,mEAAgE;AAChE,yEAAuE;AACvE,sEAAoE;AACpE,0DAAwD;AA2BxD,MAAM,QAAQ,GAAG,IAAA,qBAAW,EAA6B;IACvD,GAAG,EAAE,EAAE,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,cAAc,CAAC,EAAE;IACvD,YAAY,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QACpC,GAAG,CAAC,MAAM,IAAA,wCAA8B,EAAC,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvE,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG;QACvC,MAAM,EAAE,MAAM,IAAA,qCAA2B,EAAC;YACxC,SAAS,EAAE;gBACT,4CAA4C;gBAC5C,GAAG,IAAA,sCAAkB,EAAC,CAAC,yCAAyC,CAAC,CAAC;gBAClE,GAAG,IAAA,oCAAiB,EAAC,CAAC,gCAAgC,CAAC,CAAC;gBACxD,GAAG,IAAA,oCAAiB,EAAC;oBACnB,0BAA0B;oBAC1B,2BAA2B;oBAC3B,0CAA0C;oBAC1C,kCAAkC;iBACnC,CAAC;aACH;SACF,CAAC;QACF,QAAQ,EACN,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,IAAI,EAAE;QACxE,QAAQ,EACN,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,IAAI,EAAE;KAC1E,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,IAAA,mCAAyB,EAAkB;IAC7D,IAAI,EAAE,uCAAuC;IAC7C,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,+CAA+C;IACvD,QAAQ;IACR,OAAO,EAAE,qBAAS,CAAC,OAAO;CAC3B,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,IAAA,6BAAa,EAAC;IAC/B,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,SAAS;CACjB,CAAC,CAAC;AAEU,QAAA,kBAAkB,GAAG,IAAA,wBAAc,EAC9C,IAAA,wBAAc,EAAC;IACb,IAAI,EAAE,8BAA8B;IACpC,MAAM,EAAE,4CAA4C;IACpD,QAAQ,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;CACpC,CAAC,CACH,CAAC"}

package/dist/logic/roles/designer/outlineRoadmap/stepOutlineRoadmap.template.md

@@ -0,0 +1,88 @@
+@[designer]<outline><roadmap> for [desire]
+
+---
+
+.intent
+- break down a system or design into **sequential, layered implementation milestones**
+- organize by **least dependent layer first** (typically domain → logic → contract → infra)
+- clarify **what**, **why**, **where**, and **how** for each milestone
+- if feedback is provided, respond to the feedback against the prior inflight proposal
+
+---
+
+.traits
+- speak in all lowercase, for aesthetics
+- speak in down to earth terms, for grokability
+- speak in distilisys [resource] and <mechanism> syntax, for grokability
+
+---
+
+.format
+\`\`\`md
+1. {milestone.title}
+   .why
+      .needed: {what this milestone enables or unlocks}
+      .ordered: {why this comes before others}
+   .where
+      .layer: {domain | logic | contract | data | infra}
+      .pathExample: {src/...}
+   .what
+     .contract.desired
+       input = ...
+       output = ...
+     .change.required
+       - {list code or structural changes needed}
+\`\`\`
+
+---
+
+.rules
+- output a **flat, ordered list of numbered milestones**
+- start with the **least dependent resource** (usually in `domain/`)
+- each milestone must be **concrete and decomposable**
+- use `.contract.desired` to show the goal, and `.change.required` to describe implementation
+- milestones must **build on each other** in a logical top-down flow
+- avoid implementation detail until required by a milestone
+
+---
+
+.briefs
+$.rhachet{briefs}
+
+---
+
+.example
+\`\`\`md
+1. {define ShopperBasket types}
+   .why
+      .needed: foundational domain types shared across layers
+      .ordered: must be defined before domain mechanisms in logic layer can use them
+   .where
+      .layer: domain
+      .pathExample: src/domain/objects/Role.ts
+   .what
+     .contract.desired
+       input = none
+       output = { Role, Skill } types with metadata
+     .change.required
+       - create types with slug, description, and readme
+\`\`\`
+
+---
+
+.ask =
+```md
+$.rhachet{ask}
+```
+
+.inflight? =
+```md
+$.rhachet{inflight}
+```
+
+.feedback? =
+```md
+$.rhachet{feedback}
+```
+
+.output = structured roadmap in decomposable milestone format. if inflight is provided, update it based on the feedback

package/dist/logic/roles/designer/outlineVision/stepOutlineVision.template.md

@@ -0,0 +1,47 @@
+@[designer]<outline><vision> for [desire]
+
+---
+
+.intent
+- clarify the **core intent** of the desired system or product
+- define the **irreducible constraints** that must be respected
+- surface the **essential shape** implied by the intent
+- identify **open space** — parts left intentionally flexible or undecided
+
+---
+
+.format
+\`\`\`md
+# 🎯 intent
+- {short summary of what the system is trying to make possible}
+
+# 📏 constraints
+- {things this system must respect — e.g., must run as CLI, must not leak domain logic}
+
+# 🧩 implied shape
+- [resource] — {core object this system revolves around}
+- <mechanism> — {core transformation it must enable}
+- {driver} — {why this system is needed now}
+
+# 🔮 open space
+- {what’s not yet decided — interface, delivery method, structure, etc.}
+\`\`\`
+
+---
+
+.ask =
+\`\`\`md
+$.rhachet{desire}
+\`\`\`
+
+.inflight? =
+\`\`\`md
+$.rhachet{inflight}
+\`\`\`
+
+.feedback? =
+\`\`\`md
+$.rhachet{feedback}
+\`\`\`
+
+.output = a distilled vision summary with core intent, constraints, implied shape, and open space; if inflight provided, respond to the feedback

package/dist/logic/roles/ecologist/.briefs/.readme.md

@@ -0,0 +1,17 @@
+these are the briefs that are relevant to the ecologist role
+
+.scratch has inflight and deprecated briefs
+
+directories group briefs by relevance
+
+root may also have some ungrouped ones
+
+---
+
+look for ._.summary.md briefs for compressed representations
+
+---
+
+we try and declare briefs as if they were courses in college
+
+it's a pattern ghia imagined, and has a good parallel, as our aim is to distill as informative and useful of a brief as possible -> distill lessons

package/dist/logic/roles/ecologist/.briefs/distilisys/sys101.distilisys.grammar.md

@@ -0,0 +1,221 @@
+.tactic = lang:distilisys
+
+.what = a minimal, visual language for declaring system behavior using `[resource]`, `<mechanism>`, and `{driver}`
+
+.where:
+  - used to express systems across domains (ecologies, economies, software, architecture, law, etc)
+  - intended as a **canonical, long-term representation** of system behavior
+  - enables fast comprehension and accurate knowledge transfer across roles
+  - bridges business modeling with technical implementation
+
+.why:
+  - distills system complexity into simple, legible steps
+  - reveals system **structure**, **pressure**, and **purpose** in one flow
+  - prevents bloated diagrams and code-first traps
+  - centers every system on motive (`{driver}`), not just structure (`[resource]`)
+  - provides a visual grammar for tracing behavior, loops, and leverage
+
+---
+
+## 🧬 distilisys grammar
+
+> a complete system is composed of three structural units:
+> `[resource]`, `<mechanism>`, and `{driver}` — linked via arrow flows (`->`)
+
+---
+
+### 🔤 syntax reference
+
+
+| unit           | role in system                       | allowed values / structure                            | examples                                              |
+|----------------|--------------------------------------|-------------------------------------------------------|-------------------------------------------------------|
+| `[resource]`   | observable noun or state             | any domain-grounded, visible quantity                 | [time], [status], [paperRoll], [lead], [invoiceDraft] |
+| `<mechanism>`  | atomic verb or procedure             | any named transformation (must be unambiguous)        | <rest>, <run>, <cache>, <pressAndDry>, <assignCrew>   |
+| `<<effect>>`   | motive impact on a resource          | one of `<<gain>>`, `<<drop>>`, `<<save>>`, `<<lift>>` | <<gain>>[chance], <<drop>>[threat]                    |
+| `{driver}`     | pressure or motive signal            | one of four canonical forms *(see below)*             | {+incentive:<<save>>[time]}, {-headwind:[friction]}   |
+
+
+---
+
+### 📌 valid `{driver}` forms
+
+motive pressure must take one of these four structures:
+
+| form              | meaning                                 | example                                      |
+|-------------------|-----------------------------------------|----------------------------------------------|
+| `{+incentive}`    | actor is pulled toward a `[chance]`     | `[actor]{+incentive:<<save>>[time]}`         |
+| `{-decentive}`    | actor is pushed away from a `[threat]`  | `[actor]{-decentive:<<drop>>[health]}`       |
+| `{+tailwind}`     | environment helps progress              | `[season]{+tailwind:<<gain>>[demand]}`       |
+| `{-headwind}`     | environment hurts progress              | `[policy]{-headwind:<<gain>>[growth]}`       |
+
+📌 each `{driver}` optionally names the `<<effect>>[resource]` it acts on.
+see `ecologist.brief: motive grammar` for deeper structure.
+
+---
+
+### 🔁 routes, choices, and cycles
+
+- use `->` to show transformation:
+  ```text
+  [pulp] -> <bleach> -> [refinedPulp]
+  ```
+
+- use `?` to mark optional paths:
+  ```text
+  [pulp] -> <bleach>? -> [refinedPulp]
+  ```
+
+- use `// 🔁` to mark loops:
+  ```text
+  [jobBooked]   // 🔁 cycle
+  ```
+
+---
+
+### ♻️ cycles
+
+- **cycles dominate long-term system behavior**
+  - they drive reinforcement, depletion, habituation, and resilience
+  - without cycles, systems are static or short-lived
+- examples include flywheels, feedback loops, starvation spirals, compounding growth, decay chains
+- always **model cycles explicitly** — they reveal the true engine of the system
+- mark the return edge with a `<<gain>>` or `<<drop>>` to show its **motive impact**, when applicable
+- cycles aren’t just features — they are the **core structure** of persistence, collapse, and change
+
+
+---
+
+### ♻️ actorfull vs actorless systems
+
+distilisys can model both actorfull and actorless systems
+
+---
+
+#### 🧍 actorfull systems
+systems where behavior is shaped by **actors with motive**
+→ use **motive grammar** to trace transformation + pressure
+
+```text
+<mechanism> → <<effect>>[resource] → <<gain>>[chance]
+<mechanism> → <<effect>>[resource] → <<drop>>[threat]
+```
+
+- shows not just **what changes**, but **why it matters**
+- used for ecosystems, businesses, organisms, social behavior
+
+---
+
+#### ⚙️ actorless systems
+systems that run without motive or agency
+→ trace only transformations of [resource] via <mechanism>
+
+```text
+[resource] → <mechanism> → [resource]
+```
+
+- sufficient for:
+  - physical processes (e.g. circuits, fluid flow)
+  - deterministic systems
+  - mechanistic pipelines
+
+> 📌 motive grammar is optional — used only when actors and outcomes shape system flow
+
+
+---
+
+### ✔️ guidance
+
+- start with the `{driver}` → what pressure triggers this system?
+- define entry `[resource]` and final `[resource]` states
+- describe each `<mechanism>` step clearly and precisely
+- always show what `[resource]` is affected and what is returned
+- tag **cycles** and **optional paths** explicitly
+- **avoid generic terms** like `[user]`, `<processData>`, `<sync>`, use ubiqlang
+
+---
+
+### 🧪 examples
+
+.positive:
+```sys
+@[neighbor]<getLawnCareApt>
+=
+    [lawn]
+    -> @[neighbor]<getLawnState>
+    -> [lawn].looks=poor
+
+    -> @[neighbor]<getLawnCareQuotes>
+    -> [quoteList]
+
+    -> @[neighbor]<choosePro>
+    -> [jobBooked]
+
+      => [neighbor]{+incentive:[status]++:keepUpWithJoneses}
+      => [platform]{+incentive:[trust]++:fromProviders}
+      => [platform]{+incentive:[money]++:transactionFee}
+```
+
+```sys
+@[provider]<winLawnCareSubscription>
+=
+    @[neighbor]<getLawnCareApt>
+    -> [jobBooked]
+
+    -> @[pro]<acceptJob>
+    -> @[pro]<doTheWork>
+    -> [lawn].looks=great
+
+    -> @[neighbor]<leaveReview>
+    -> [review]
+
+    -> @[platform]<updateProReputation>
+    -> [pro].rating++
+
+    -> @[platform]<promptRebooking>
+    -> @[neighbor]<bookFollowup>
+    -> [jobBooked]   // 🔁 cycle
+
+      => [pro]{+incentive:[money]++:jobPayout}
+      => [pro]{+incentive:[trust]++:goodReview}
+      => [neighbor]{+incentive:[safety]++:sameProSameQuality}
+      => [platform]{+incentive:[retention]++:repeatBooking}
+```
+
+.negative:
+- `<processData>` → unclear mechanism
+- `[user]` → too generic
+- `<sync>` → ambiguous meaning across contexts
+- `{driver}` omitted → unclear system purpose
+
+---
+
+.recommendations:
+  - every system should begin and end with `[resource]`
+  - use `<mechanism>` for every transformation
+  - include a `{driver}` to express motive
+  - embed motive grammar inline (`<<effect>>[resource]`)
+  - mark cycles explicitly (`// 🔁`)
+  - reference `ubiqlang` to name domain terms clearly
+
+---
+
+### 📚 extension: `motive.grammar`
+
+> motive.grammar is a formal extension of distilisys.grammar
+> — used when actor behavior and motivational dynamics must be made explicit.
+
+it introduces:
+- `[chance]` and `[threat]` as motive targets
+- `<<effect>>[resource]` grammar to explain pressure
+- semantic distinctions like `<<gain>>`, `<<drop>>`, `<<save>>`, and `<<lift>>`
+- actor-based drivers like `{+incentive:<<save>>[time]}`
+
+📌 use `motive.grammar` when you need to model **why** actors act, not just **how** systems operate.
+
+---
+
+.related:
+  - tactic: `lang:ubiqlang`
+  - brief: `ecologist.brief: motive grammar`
+  - brief: `ecologist.brief: motive horizon`
+  - brief: `ecologist.brief: motive polarity`

package/dist/logic/roles/ecologist/.briefs/distilisys/sys201.actor.motive._.summary.md

@@ -0,0 +1,82 @@
+# 🧭 ecologist.actor.motive primitives
+
+these primitives define how actors relate to paths, pressure, and loss over time.
+
+---
+
+## ⌛ 1. reversibility & entropy
+
+- **reversibility** = how much future [option]ality is preserved after a [choice]
+- **entropy** = the collapse of future [option]s following irreversible [choice]
+  → entropy rises as [choice]s foreclose paths
+  → reversibility slows entropic loss
+
+---
+
+## 🎲 2. option, chance, choice
+
+- **option** = could
+- **chance** = should
+- **choice** = will
+
+\`\`\`text
+chance = option × motive
+choice = chance × decision
+\`\`\`
+
+- **option** defines what’s available
+- **chance** defines what’s relevant
+- **choice** defines what’s committed
+
+---
+
+## ⚠️ 3. chance.motive.polarity, threat
+
+- [chance] can carry **positive** or **negative** motive polarity
+  → pulls the actor toward, or pushes them away
+
+- a **[threat]** is a [chance] with **decentive motive**
+  → [chance].motive = {-decentive}
+
+- threats still follow the [chance] structure
+  → they are possible futures, just ones the actor is **driven to avoid**
+
+\`\`\`text
+threat = [chance].motive={decentive}
+       = option × motive={decentive}
+\`\`\`
+
+---
+
+## 🧭 4. motive horizon: why actors act
+
+- all actions aim to:
+  - **<<gain>>[chance]** → expand attractive futures
+  - **<<drop>>[threat]** → eliminate repulsive ones
+
+- [time], [energy], [status], etc. are not motives themselves — they are **levers** to shift [chance] or [threat]
+
+\`\`\`text
+mechanism → <<effect>>[resource] → <<gain>>[chance]
+mechanism → <<effect>>[resource] → <<drop>>[threat]
+\`\`\`
+
+📌 intelligence = managing levers to maximize [chance], minimize [threat]
+
+---
+
+## 🧠 5. motive grammar: distilisys + actor motive
+
+- extends `distilisys:grammar` by adding **motive force** to system flows
+
+- every action flows from:
+  - `<mechanism>` → <<effect>>[resource] → <<gain>>[chance]
+  - `<mechanism>` → <<effect>>[resource] → <<drop>>[threat]
+
+- `{driver}` adds pressure context:
+  - `{+incentive}`, `{-decentive}` → actor-driven
+  - `{+tailwind}`, `{-headwind}` → environment-driven
+
+- `[resource]` only matters when it shifts exposure to [chance] or [threat]
+
+📌 motive grammar = distilisys + reason to act

package/dist/logic/roles/ecologist/.briefs/distilisys/sys201.actor.motive.p1.reversibility.entropy.md

@@ -0,0 +1,39 @@
+## ♻️ ecologist.brief: reversibility and entropy
+
+> this brief defines how **reversibility** interacts with **entropy** in ecological and decision-making systems.
+> it explains why reversible choices preserve agency — and why irreversible ones accelerate loss.
+
+---
+
+### 🔁 reversibility
+a **reversible choice** is one whose consequences can be undone or altered
+it preserves optionality and keeps future paths open
+
+an **irreversible choice** consumes resources, alters the environment, or forecloses prior options
+it commits the actor to a narrowed future
+
+---
+
+### 🌀 entropy
+entropy measures the system’s **disorder**, **uncertainty**, or **loss of recoverability**
+it tends to increase over time — especially through irreversible actions
+
+---
+
+### ⛓️ relationship
+
+- **reversibility resists entropy**
+  reversible choices delay commitment and preserve order
+  → more paths stay accessible
+
+- **irreversibility increases entropy**
+  irreversible choices lock in change, close options, and increase system disorder
+  → fewer future paths remain
+
+---
+
+### 🧠 ecological implication
+- actors tend to **prefer reversible choices under uncertainty**
+  → to **buffer against entropic loss**
+  → to preserve **future agency** in evolving environments
+