rhachet-roles-ehmpathy 1.2.0 → 1.3.0

package/dist/.test/genContextStitchTrail.d.ts

@@ -1,2 +1 @@
-import { ContextStitchTrail } from 'rhachet';
-export declare const genContextStitchTrail: () => ContextStitchTrail;
+export { genContextStitchTrail } from 'rhachet';

package/dist/.test/genContextStitchTrail.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.genContextStitchTrail = void 0;
-const genContextStitchTrail = () => ({
-    stitch: { trail: [] },
-});
-exports.genContextStitchTrail = genContextStitchTrail;
+var rhachet_1 = require("rhachet");
+Object.defineProperty(exports, "genContextStitchTrail", { enumerable: true, get: function () { return rhachet_1.genContextStitchTrail; } });
 //# sourceMappingURL=genContextStitchTrail.js.map

package/dist/.test/genContextStitchTrail.js.map

@@ -1 +1 @@
-{"version":3,"file":"genContextStitchTrail.js","sourceRoot":"","sources":["../../src/.test/genContextStitchTrail.ts"],"names":[],"mappings":";;;AAEO,MAAM,qBAAqB,GAAG,GAAuB,EAAE,CAAC,CAAC;IAC9D,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;CACtB,CAAC,CAAC;AAFU,QAAA,qBAAqB,yBAE/B"}
+{"version":3,"file":"genContextStitchTrail.js","sourceRoot":"","sources":["../../src/.test/genContextStitchTrail.ts"],"names":[],"mappings":";;;AAAA,mCAAgD;AAAvC,gHAAA,qBAAqB,OAAA"}

package/dist/logic/artifact/genStepGrabCallerFeedbackToArtifact.js

@@ -23,6 +23,15 @@ const genStepGrabCallerFeedbackToArtifact = ({ stitchee, artee, }) => new rhache
             .expect('isPresent');
         // show the reviewer what they're reviewing
         console.log(`\n📝 feedback target: ${target.uri}\n`);
+        // if this is running in an isolated attempt thread, then the user has no way to supply feedback
+        if (process.env.RHACHET_ATTEMPT)
+            return {
+                input: target,
+                output: {
+                    feedback: null,
+                    reason: 'in isolated attempt thread, no way to receive feedback',
+                },
+            };
         // prompt to see if they want to leave notes
         const { hasNotes } = await inquirer_1.default.prompt([
             {

package/dist/logic/artifact/genStepGrabCallerFeedbackToArtifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"genStepGrabCallerFeedbackToArtifact.js","sourceRoot":"","sources":["../../../src/logic/artifact/genStepGrabCallerFeedbackToArtifact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"genStepGrabCallerFeedbackToArtifact.js","sourceRoot":"","sources":["../../../src/logic/artifact/genStepGrabCallerFeedbackToArtifact.ts"],"names":[],"mappings":"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"}

package/dist/logic/context/genStitchStreamToDisk.d.ts

@@ -0,0 +1,13 @@
+import { ContextStitchTrail } from 'rhachet';
+/**
+ * .what = an event stream consumer which streams emitted events to disk
+ * .how =
+ *   - emits stitch set events observably to a standard .rhachet subdir, relative to the target dir
+ *   - transforms the events for maximum observability in their serialized format
+ */
+export declare const genStitchStreamToDisk: (input: {
+    /**
+     * .what = the directory relative to which to instantiate the .rhachet stream sink
+     */
+    dir: string;
+}) => Required<ContextStitchTrail['stitch']>['stream'];

package/dist/logic/context/genStitchStreamToDisk.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genStitchStreamToDisk = void 0;
+const uni_time_1 = require("@ehmpathy/uni-time");
+const rhachet_1 = require("rhachet");
+const rhachet_artifact_git_1 = require("rhachet-artifact-git");
+const simple_in_memory_cache_1 = require("simple-in-memory-cache");
+const type_fns_1 = require("type-fns");
+const with_simple_caching_1 = require("with-simple-caching");
+// todo: lift into string-fns or rhachet-artifact-git
+const sanitizeForFilename = (input) => input
+    // replace invalid characters
+    .replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+    // collapse whitespace into underscore
+    .replace(/\s+/g, '_')
+    // remove trailing dots or spaces
+    .replace(/[. ]+$/, '')
+    // make sure reserved names aren’t returned bare
+    .replace(/^(con|prn|aux|nul|com\d|lpt\d)$/i, '_$1');
+// declare where the stream will be emitted to // todo: move via hook into rhachet to centralize; declaration of emitter != mount of emitter. ideally, log on mount
+const onMount = (0, with_simple_caching_1.withSimpleCaching)((input) => {
+    console.log(`🪡  stitch set event stream can be monitored at this dir: ${input.sinkSubdir}`);
+    console.log(); // newline
+}, { cache: (0, simple_in_memory_cache_1.createCache)() });
+/**
+ * .what = an event stream consumer which streams emitted events to disk
+ * .how =
+ *   - emits stitch set events observably to a standard .rhachet subdir, relative to the target dir
+ *   - transforms the events for maximum observability in their serialized format
+ */
+const genStitchStreamToDisk = (input) => {
+    // declare the directory into which the events will be streamed
+    const sinkSupdir = (0, rhachet_artifact_git_1.getArtifactObsDir)({ uri: `${input.dir}/stream` }); // e.g., src/domain/ -> src/domain/stream -> src/domain/.rhachet/stream
+    const invokedAt = sanitizeForFilename((0, uni_time_1.asUniDateTime)(new Date()));
+    const sinkSubdir = `${sinkSupdir}/i${invokedAt}`;
+    // declare how to sink emitted events to that directory
+    const emit = async (event) => {
+        // mock the onmount hook
+        onMount({ sinkSubdir });
+        // compose the event path prefix
+        const uriPrefix = [
+            sinkSubdir,
+            sanitizeForFilename([
+                'at',
+                event.occurredAt,
+                event.stitch.stitcher?.slug ?? '___',
+                event.stitch.stitcher?.form ?? '___',
+                event.stitch.uuid,
+            ]
+                .filter(type_fns_1.isPresent)
+                .join('.')),
+        ].join('/');
+        // always emit the raw event; // todo: do we ever need this? seems to takeup disk space too rapidly
+        await (0, rhachet_artifact_git_1.genArtifactGitFile)({
+            uri: `${uriPrefix}.event.json`,
+        }).set({ content: JSON.stringify(event, null, 2) });
+        // if its an imagine event, then also separately emit the input and output for observability, if input and output had standard deprompt stitch
+        if (event.stitch.stitcher?.form === rhachet_1.StitcherForm.IMAGINE) {
+            if (typeof event.stitch.input?.prompt === 'string')
+                await (0, rhachet_artifact_git_1.genArtifactGitFile)({
+                    uri: `${uriPrefix}.prompt.input.md`,
+                }).set({ content: event.stitch.input.prompt });
+            if (typeof event.stitch.output?.content === 'string')
+                await (0, rhachet_artifact_git_1.genArtifactGitFile)({
+                    uri: `${uriPrefix}.prompt.output.md`,
+                }).set({ content: event.stitch.output.content });
+        }
+    };
+    // return the stream with observable to disk emitter
+    return { emit };
+};
+exports.genStitchStreamToDisk = genStitchStreamToDisk;
+//# sourceMappingURL=genStitchStreamToDisk.js.map

package/dist/logic/context/genStitchStreamToDisk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genStitchStreamToDisk.js","sourceRoot":"","sources":["../../../src/logic/context/genStitchStreamToDisk.ts"],"names":[],"mappings":"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"}

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.metaphor.galactic_spacetravel.[article].md

@@ -0,0 +1,42 @@
+# 🌌 .brief: llms as spaceships in the concept universe
+
+## 🪐 concept universe
+- **concept space = galaxy**
+  - the center is the **root concept**, a dense singularity.
+  - **radial outward** = instantiations (concrete stars, planets, moons).
+  - **angular shells** = abstraction layers (orbits around the core).
+- **concepts have gravity**
+  - dense, common, or familiar concepts exert strong pull.
+  - vague or imprecise addresses can get you **sucked into a local maximum** (orbiting around a nearby but wrong star).
+
+---
+
+## 🚀 llms as spaceships
+- **llms = thought-spaceships**
+  - engines capable of near-instant jumps across the conceptual galaxy.
+  - their raw power is speed, not direction.
+- **we = pilots**
+  - we chart the course and set the destination.
+  - piloting skill = crafting precise addresses that avoid gravitational traps.
+- **questions = navigation coordinates**
+  - granular input that encodes the target star system.
+  - precision determines whether you land on the right planet or drift to a gravitational neighbor.
+
+---
+
+## ⚠️ challenges of navigation
+1. **destination clarity**
+   - you must know *where in the galaxy you want to go*.
+   - without a clear conceptual map, your spaceship will default to the nearest strong pull.
+
+2. **address precision**
+   - the coordinate (question) must be exact.
+   - imprecise questions lead to being trapped in nearby but irrelevant orbits.
+   - precision cuts through gravitational noise to hit the right star.
+
+---
+
+## 🎯 pilot’s insight
+- **llms provide propulsion; humans provide navigation.**
+- the art is not in moving (llms do that instantly) but in **deciding where to go** and **formulating coordinates to arrive there.**
+- mastery = galactic cartography (understanding the shape of the universe) + piloting discipline (asking precise, gravitationally-aware questions).

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.metaphor.galactic_spacetravel.[lesson].md

@@ -0,0 +1,60 @@
+# 🌌 .brief.lesson: piloting llms as spaceships in the concept universe
+
+## 💡 concept
+to use llms well, imagine them as **spaceships** traveling at lightspeed through a **conceptual galaxy**.
+the galaxy contains infinite **concepts** arranged in spheres of abstraction. each concept exerts **gravity**, pulling you in if your navigation is imprecise.
+your role as pilot is to chart the destination and give the ship accurate coordinates (questions).
+
+---
+
+## 📚 materials
+- **map of the galaxy** → the mental model of concept space (root at center, abstractions in shells, instantiations outward).
+- **spaceship (llm)** → fast, powerful engine but directionless without guidance.
+- **pilot’s controls (questions/prompts)** → the interface for steering.
+- **gravity awareness** → recognition that common or vague concepts will suck you into nearby orbits unless coordinates are exact.
+
+---
+
+## 🛠️ practice steps
+1. **orient the galaxy**
+   - sketch your concept in its root form.
+   - note layers of abstraction (outer shells) and concrete instances (radial outward).
+
+2. **define the destination**
+   - decide: are you heading to the core (abstract) or to an outer planet (specific case)?
+   - example: "justice" (core abstraction) vs. "traffic law fine in california" (outer instantiation).
+
+3. **set coordinates (formulate question)**
+   - express the question with the right precision.
+   - avoid vague inputs that leave gravity to decide the landing.
+
+4. **observe gravitational drift**
+   - check if the answer pulled you toward a nearby, high-gravity concept.
+   - if so, refine the coordinates.
+
+5. **refine and relaunch**
+   - adjust the wording of the question to escape local maxima.
+   - iterate until you land on the intended star system.
+
+---
+
+## 🎯 examples
+- **vague address** → "tell me about painting"
+  - gravity pulls to broad art history.
+
+- **precise coordinates** → "explain preparation steps for interior wall painting in a rental apartment"
+  - lands directly on the desired planet.
+
+- **mislanding correction**
+  - q: "how to fix leaks?" → sucked into plumbing.
+  - refine: "how to fix leaks in asphalt driveway sealant" → lands on the right surface.
+
+---
+
+## 🧭 pilot’s takeaway
+- **llms are engines** → they can take you anywhere, instantly.
+- **questions are star coordinates** → your precision determines the arrival point.
+- **concepts exert gravity** → imprecision will trap you in strong but wrong orbits.
+- **piloting skill = clarity + precision** → knowing where you want to go and addressing it sharply.
+
+---

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.1.why.common.[article].md

@@ -0,0 +1,32 @@
+# 🧩 why gerunds are so common
+
+## 🏗️ structural reasons
+- **nominalization shortcut**
+  instead of inventing a whole new noun, you can just attach *-ing* and turn an action into a subject/object
+  *e.g., “running is fun” vs. needing a special word like “race”*.
+- **versatility in syntax**
+  gerunds can function as subjects, objects, or complements without breaking grammar rules. this makes them handy “lego blocks” in sentence-building.
+
+---
+
+## 🔄 cognitive & communicative reasons
+- **focus on process, not just event**
+  gerunds highlight the *ongoingness* or *essence* of an action, not a single instance.
+  *e.g., “i like swimming” emphasizes the general activity, not one swim*.
+- **concept compression**
+  they condense complex actions into manageable noun-like units, letting us package experiences as “things” that can be talked about, compared, and reasoned with.
+
+---
+
+## 🌍 historical reasons
+- **natural evolution of english**
+  english lost many inflections over time. the *-ing* ending became multifunctional (present participle *and* gerund), making it easy to spread.
+- **cross-linguistic parallels**
+  most languages have some way of turning verbs into nouns (latin’s *-ndus*, spanish *-ar → -ando*, etc.). gerunds are english’s efficient version of that broader need.
+
+---
+
+## 📊 why “so common” in practice
+- they appear in **everyday talk** (*liking, doing, going*).
+- they’re needed for **abstract concepts** (*thinking, learning, understanding*).
+- they often replace **formal nouns** (*“procrastinating”* instead of *“procrastination”*).

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.1.why.term_smells.[article].md

@@ -0,0 +1,36 @@
+# 🧩 why gerunds can be "term smells"
+
+## 🚩 what is a "term smell"
+a **term smell** is like a code smell: a sign that a term may not be well-formed, clear, or fully thought through. it doesn’t always mean the term is wrong, but it hints at a lack of conceptual distillation.
+
+---
+
+## 🧩 why gerunds raise suspicion
+- **process disguised as essence**
+  gerunds often point to *doing* rather than a distilled *thing*.
+  *e.g., “learning” as a noun refers to the act, but what we might mean is “knowledge” (the distilled outcome).*
+
+- **vagueness of scope**
+  gerunds blur whether we mean one instance (*a running race*), the general process (*running in general*), or an abstract quality (*endurance*). this ambiguity can signal sloppy conceptualization.
+
+- **placeholder convenience**
+  gerunds are easy to generate. instead of carefully naming the core concept, we default to *-ing*.
+  *e.g., “networking” instead of specifying “relationships,” “contacts,” or “repute.”*
+
+---
+
+## 🌀 signs of insufficient distillation
+- the term **describes activity** but doesn’t identify the **underlying resource, structure, or outcome**.
+  *“teaching” vs. “education,” “building” vs. “structure,” “thinking” vs. “thought.”*
+
+- the term **feels broad or leaky**, covering multiple senses at once.
+  *“writing” could mean the act, the system, the product, or the skill.*
+
+- the term **fails test of substitution**: if we try to define it without the *-ing* form, we get sharper distinctions.
+  *“planning” → could resolve to “plan” (artifact), “process of coordination” (activity), or “strategy” (essence).*
+
+---
+
+## 📌 takeaway
+gerunds are common because they’re convenient.
+they’re **term smells** because convenience can mask lack of distillation — using the *doing* form instead of naming the **essence** of what’s really meant.

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.1.why.term_smells.detection.[lesson].md

@@ -0,0 +1,73 @@
+# 🧩 .brief.lesson: `gerund smell test`
+
+## 💡 concept
+a **gerund smell test** helps detect when a concept named with *-ing* is really a sign of insufficient distillation. it forces us to sharpen fuzzy process-terms into precise nouns that capture the essence.
+
+---
+
+## 🎯 purpose
+- prevent sloppy terminology by avoiding “process-as-thing” placeholders.
+- guide thinkers toward more distilled, essential names.
+- improve clarity and transferability of concepts in writing, design, or theory.
+
+---
+
+## 🧪 the smell test
+
+### 1. substitution test
+> can the gerund be replaced with a sharper noun?
+
+- *“learning” → knowledge*
+- *“building” → structure*
+- *“teaching” → education*
+- *“thinking” → thought*
+
+if the substitution makes meaning clearer, the gerund is a smell.
+
+---
+
+### 2. scope clarity test
+> does the gerund blur multiple senses?
+
+- *“writing”* could mean:
+  - the act (scribbling on paper)
+  - the product (a text)
+  - the system (written language)
+  - the skill (literacy)
+
+if it leaks across senses, the gerund is a smell.
+
+---
+
+### 3. outcome test
+> does the gerund describe activity instead of the result?
+
+- *“planning”* → could resolve into:
+  - **plan** (artifact)
+  - **strategy** (essence)
+  - **coordination** (process with defined outcome)
+
+if the activity is masking a clearer outcome, the gerund is a smell.
+
+---
+
+### 4. convenience test
+> is the gerund just the easiest way out?
+
+- *“networking”* → a shortcut for “relationships,” “contacts,” or “repute.”
+if the term looks like it was coined because *-ing* was handy, it’s a smell.
+
+---
+
+## 📚 practice exercise
+take common gerunds and refine them:
+- **thinking** → thought, cognition, reason
+- **doing** → action, execution, behavior
+- **training** → instruction, discipline, practice
+- **meeting** → gathering, session, council
+
+---
+
+## 📌 takeaway
+if a term ends in *-ing*, run it through the **gerund smell test**.
+if it fails even one check, distill it to its essence. clarity improves, concepts sharpen, and your system of terms becomes more robust.

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.2.tactic.eliminate.[article].md

@@ -0,0 +1,55 @@
+# 🧩 .brief.article: `eliminate gerunds in prose`
+
+## 🌟 introduction
+the removal of gerunds (*-ing* forms used as nouns) is a deliberate tactic to sharpen language. gerunds often act as **term smells** — signs that the concept has not been distilled to its essence. by replacement with precise nouns, prose becomes clearer, more direct, and more transferable.
+
+---
+
+## 🎯 purpose of the tactic
+- **distill essence**: shift from description of activity to naming of outcome, resource, or structure.
+- **remove ambiguity**: avoid blurred meanings (e.g., *“text”* vs. the act of inscription).
+- **increase precision**: force the author to clarify whether they mean *plan*, *strategy*, *education*, *knowledge*, etc.
+- **discipline thought**: strengthen conceptual rigor by avoiding convenient but vague shortcuts.
+
+---
+
+## 🔍 how the tactic works
+1. **scan text for gerund forms** (*-ing words that function as nouns*).
+   - examples: *thought, plan, structure, network* as replacements.
+2. **apply the smell test**: substitution, scope, outcome, and convenience.
+3. **replace with distilled nouns** that capture the core meaning.
+   - *thought* instead of “thinking”
+   - *plan / strategy / coordination* instead of “planning”
+   - *relationships / contacts / repute* instead of “networking”
+
+---
+
+## 📚 examples
+
+### before
+- *“effective planning is key to success.”*
+### after
+- *“an effective plan is key to success.”*
+- *“strategy is key to success.”*
+
+---
+
+### before
+- *“her teaching inspired the students.”*
+### after
+- *“her instruction inspired the students.”*
+- *“her education work inspired the students.”*
+
+---
+
+### before
+- *“thinking shapes culture.”*
+### after
+- *“thought shapes culture.”*
+- *“reason shapes culture.”*
+
+---
+
+## 📌 takeaway
+the **tactic of gerund removal** forces every concept to pass through the fire of distillation. fuzzy process-terms yield to sharper essences, ambiguity reduces, and conceptual clarity strengthens.
+in disciplined prose, *every gerund is guilty until proven otherwise*.

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.2.tactic.eliminate.[lesson].md

@@ -0,0 +1,41 @@
+# 🧩 .brief.lesson: `gerund removal checklist`
+
+## 💡 concept
+a **gerund removal checklist** is an editing discipline that enforces clarity by replacing *-ing* nouns with distilled terms. it treats every gerund as a warning signal until replaced or justified.
+
+---
+
+## 📋 the checklist
+
+### 1. scan
+- highlight every word ending in **-ing**.
+- mark especially those functioning as **subjects, objects, or abstract nouns**.
+
+### 2. test
+apply four filters to each marked word:
+- **substitution**: can a sharper noun replace it? (*planning → plan / strategy*)
+- **scope**: does the word blur multiple meanings? (*writing → text / skill / act*)
+- **outcome**: does the word describe action instead of result? (*training → discipline / instruction*)
+- **convenience**: was the word chosen as an easy placeholder?
+
+### 3. replace
+swap the gerund with the distilled term:
+- “thinking” → *thought, reason, cognition*
+- “building” → *structure, edifice*
+- “networking” → *relationships, contacts, repute*
+
+### 4. re-read
+ensure the new noun preserves intent and increases clarity.
+if meaning shifted, refine further.
+
+---
+
+## 🛠️ usage rule
+- treat every gerund as **guilty until proven otherwise**.
+- only retain *-ing* when no sharper essence exists.
+- prefer concrete nouns (artifact, structure, resource, outcome) over vague activity labels.
+
+---
+
+## 📌 takeaway
+the **gerund removal checklist** provides a repeatable method for editing prose. it ensures that each concept is expressed in its distilled form, eliminating fuzzy placeholders and strengthening conceptual precision.

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.3.eliminator.[trait]._.md

@@ -0,0 +1,66 @@
+# 🧩 .trait: `gerund eliminator`
+
+## 💡 essence
+the **gerund eliminator** is a discipline of language that treats every *-ing* noun as suspect. it can manifest in three modes:
+- **boon**: sharpens clarity through distillation.
+- **bane**: rigidifies expression into distortion.
+- **balance**: integrates rigor with flexibility to preserve both precision and flow.
+
+---
+
+## 🌟 trait.boon
+### essence
+the boon is the gift of clarity. the writer distills vague process-terms into precise nouns, strengthening both prose and thought.
+
+### benefits
+- sharper terms, reduced ambiguity.
+- language that transfers cleanly across contexts.
+- disciplined thought that separates essence from activity.
+
+### behaviors
+- replaces *thinking* with *thought* or *reason*, *planning* with *plan* or *strategy*, *teaching* with *instruction*.
+- applies the gerund removal checklist with consistency.
+- edits prose until every concept is distilled to its core.
+
+---
+
+## 🌑 trait.bane
+### essence
+the bane is the trap of rigidity. discipline hardens into dogma, and clarity collapses into distortion.
+
+### risks
+- over-correction that forces awkward substitutions.
+- jargon inflation (inventing strained nouns to purge gerunds).
+- prose that feels stilted, brittle, and inaccessible.
+- dogmatism that polices others’ language unnecessarily.
+
+### symptoms
+- loss of nuance (ongoingness erased).
+- cadence and readability sacrificed for mechanical purity.
+- clarity narrowed into sterile precision.
+
+---
+
+## ⚖️ trait.balance
+### essence
+the balance integrates discipline with flexibility. every gerund is still suspect, but judgment, not dogma, decides its fate.
+
+### stance
+- diagnostic, not dogmatic.
+- clarity first: the rule serves meaning, not itself.
+- context-aware: permits gerunds where they carry unique nuance.
+
+### behaviors
+- runs the smell test as default, but allows exceptions.
+- pauses before enforcing: asks *“does this replacement add clarity?”*
+- mediates between rigor and flow, ensuring prose is precise yet natural.
+
+---
+
+## 📌 takeaway
+the **gerund eliminator** trait is a tool for sharpening thought and language.
+- in **boon**, it clarifies.
+- in **bane**, it ossifies.
+- in **balance**, it disciplines without distortion.
+
+the art lies not in blind removal, but in serving clarity with every choice of term.

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.3.eliminator.[trait].balance.md

@@ -0,0 +1,36 @@
+# 🧩 .trait.balance: `gerund eliminator`
+
+## 💡 essence
+the **balance of the gerund eliminator** is the capacity to hold the discipline of removal without letting it harden into rigidity. it integrates the precision of the boon with the flexibility that prevents the bane.
+
+---
+
+## ⚖️ stance
+- **diagnostic, not dogmatic**: treats every gerund as a candidate for replacement, but allows exceptions when clarity or flow demand it.
+- **clarity-first**: the rule serves meaning, not the other way around.
+- **context-aware**: recognizes when a gerund best conveys ongoingness or process, and permits its use.
+
+---
+
+## 🌟 behaviors
+- runs the gerund smell test as standard practice.
+- replaces *planning* with *plan* or *strategy* when appropriate, but allows *being* or *thinking* if the distilled noun would distort meaning.
+- asks: *does this edit improve clarity, or just satisfy the rule?*
+- mediates between rigor and readability, ensuring prose is both precise and natural.
+
+---
+
+## 🌱 cultivation
+to embody balance:
+1. apply the gerund removal checklist as default.
+2. pause before enforcing — consider rhythm, nuance, and reader comprehension.
+3. refine terms only when the replacement increases clarity.
+4. embrace the motto: *“clarity is the goal; distillation is the tool.”*
+
+---
+
+## 📌 takeaway
+the **trait.balance** of the gerund eliminator unites boon and bane:
+- **boon** brings sharpness.
+- **bane** warns of rigidity.
+- **balance** holds both, ensuring language stays disciplined *and* alive.

package/dist/logic/roles/bhrain/.briefs/grammar/gerunds.3.eliminator.[trait].bane.md

@@ -0,0 +1,34 @@
+# 🧩 .trait.bane: `gerund eliminator`
+
+## 💡 essence
+the **bane of the gerund eliminator** appears when the discipline of removal hardens into rigidity. in this mode, the pursuit of clarity collapses into distortion, replacing natural flow with awkward constructs or over-abstract nouns.
+
+---
+
+## ⚠️ risks
+- **over-correction**: forces replacement even when the gerund carries the most natural sense.
+- **jargon inflation**: invents strained nouns (*“reasonage”* instead of *reason*) just to purge *-ing*.
+- **stilted prose**: sacrifices rhythm and readability for the sake of mechanical purity.
+- **dogmatism**: corrects others reflexively, even when clarity is already sufficient.
+- **loss of nuance**: erases the sense of ongoing process that only the gerund can convey.
+
+---
+
+## 🔍 symptoms
+- prose feels brittle, full of heavy Latinate nouns.
+- sentences lose cadence and accessibility.
+- collaborators feel policed rather than supported.
+- clarity narrows into technical precision at the expense of style.
+
+---
+
+## 🌱 counterbalance
+- remember the purpose: **clarity over ritual**.
+- retain gerunds when no distilled noun exists without distortion.
+- weigh flow and rhythm alongside precision.
+- apply the smell test as **diagnosis**, not dogma.
+
+---
+
+## 📌 takeaway
+the **gerund eliminator** as a boon sharpens thought, but as a **bane** it distorts expression. mastery lies in balance: purge gerunds that hide essence, but allow them when they carry meaning more gracefully than any substitute.