rhachet-roles-ehmpathy 1.8.0 → 1.9.1

package/dist/logic/roles/architect/.briefs/criteria.given_when_then.[seed].v3.md

@@ -0,0 +1,87 @@
+use this brief to help you declare acceptance test criteria for .behavior
+
+in BDD given/when/then format
+
+================================
+
+recall:
+- acceptance.criteria should only test BEHAVIOR; never internals
+- acceptance.criteria should treat the system as a black box
+  - it doesn't care how it gets done and has no visibility into it
+  - it only cares that the usecases are satisfied for the given scenes
+  - it only engages with the system at the CONTRACT LAYER
+    - src/contract/endpoints (a.k.a. src/contract/handlers)
+    - src/contract/commands
+
+
+distinguish the criteria into
+
+BLOCKER = required; will not satisfy requireemnts without it
+and
+NITPICK = nicetohave, but not a show stoppeer
+
+
+================================
+
+here's some examples of what i mean
+
+
+[idea] = nest then's within sothat? when many thens support the same sothat?
+
+  when([t4] bastion IAM instance profile is provisioned via terraform)
+    sothat(SSM sessions can be established to bastion)
+      then(instance profile includes AmazonSSMManagedInstanceCore policy)
+      then(instance profile allows ssm:StartSession action)
+    sothat(auto-pause can detect when bastion is idle)
+      then(instance profile allows ec2:StopInstances for self-stop)
+      then(instance profile allows ec2:DescribeInstances to check instance state)
+      then(instance profile allows ssm:DescribeSessions to detect active sessions)
+      then(instance profile allows ssm:GetConnectionStatus to verify session state)
+
+
+i.e.,
+
+usecase(purpose)
+  given(scene)
+    when(cause)
+      sothat(benefit)
+        then(effect.1)
+        then(effect.2)
+
+
+---
+
+
+e.g.,
+
+usecase(eat dinner)
+  given(its dinner time)
+    when(dinner is served)
+      sothat(we can eat with cleanly)
+        then(we should have cutlery appropriate to the dish)
+        then(we should have plates appropriate to the dish)
+        then(we should have napkins to clean with)
+
+
+
+
+criteria is best written in behavior-driven-development format
+
+e.g.,
+
+given(scene)
+  when([t0] nochange)
+    then(assert initial condition)
+    ...
+  when([t1] cause)
+    then(effect)
+      sothat(benefit) # optional
+    ...
+  when([t2] cause)
+    then(effect)
+      sothat(benefit) # optional
+    ...
+
+
+dont forget that given and when can nest inside eachother; but then() goes at the root
+

package/dist/logic/roles/mechanic/.briefs/architecture/directional-dependencies.md

@@ -5,7 +5,7 @@ enforce strict top-down dependency flow across layered system boundaries — low
 
 .scope
 - applies to all folders and modules within `src/`
-- required for `contract/`, `logic/`, `data/`, and `domain/` folders
+- required for `contract/`, `access/`, `domain.objects/`, `domain.operations/`
 - governs imports, module references, and stitched flow boundaries
 
 .why
@@ -15,59 +15,68 @@ enforce strict top-down dependency flow across layered system boundaries — low
 - aligns with `arch:bounded-contexts` and enables predictable top-down orchestration
 
 .structure
-```
+\`\`\`
 src/
-  contract/        // topmost — public interfaces, local commands
-    endpoints/     // exposed APIs
-    commands/      // internal entrypoints (e.g. CLI, scripts)
-  logic/           // application procedures, stitched flows
-  data/            // infrastructure layer (daos, sdks, services)
-    daos/          // persistence logic — may reference domain objects
-    sdks/          // external clients — may reference domain types
-  domain/          // lowest — domain models, business rules
-    objects/       // canonical domain declarations
-```
+  contract/            // topmost — public interfaces, local commands
+    api/               // public invocable api endpoints, deployed and exposed by the project; e.g., via `aws-lambda`
+    cmd/               // private internal use entrypoints, supported by the project; e.g., via `as-command`
+    sdk/               // public software development kit exports, supported by the project; e.g., `export ...`
+    cli/               // public command line interface contracts, supported by the project; e.g., via `commander`
+
+  access/              // infrastructure layer (daos, sdks, svcs)
+    daos/              // private persistence logic — may reference domain objects
+    sdks/              // remote third party contracts, from any alt org — may declare their own domain.objects
+    svcs/              // remote first party contracts, from our own org — may declare their own domain.objects
+
+  domain.objects/      // canonical domain declarations
+  domain.operations/   // domain behavior + business rules
+
+  infra/               // infrastructure specific adapters
+\`\`\`
 
 .how
 - each layer may depend **only on the layers below it**
-  - `contract/` may depend on `logic/`, `data/`, `domain/`
-  - `logic/` may depend on `data/`, `domain/`
-  - `data/` may depend on `domain/`
-  - `domain/` must not depend on anything outside its own layer
-- stitched flows live in `logic/` or `contract/commands/` and orchestrate downstream only
-- never import upward across layers (e.g. `domain/` importing `data/`)
-- shared types must follow same directional rules
+  - `contract/` may depend on `domain.objects/` and `domain.operations/`
+  - `access/` may depend on `domain.objects/` and `domain.operations/`
+  - `domain.operations/` may depend on `domain.objects/` or `infra/`
+  - `domain.objects/` must not depend on anything outside its own layer
+  - `infra/` must not depend on anything outside its own layer
+
+- stitched flows live in `domain.operations/` or `contract/commands/` and orchestrate downstream only
+- never import upward across layers (e.g., `domain.objects/` importing `access/`)
+- shared types must follow the same directional rules
 
 .enforcement
-- imports that violate top-down boundary = BLOCKER
-- circular dependencies between layers = BLOCKER
-- logic in `domain/` must never reach into `data/`, `logic/`, or `contract/`
-- logic in `data/` may use `domain/`, but must stay decoupled from business rules
+- imports that violate top-down boundary = **BLOCKER**
+- circular dependencies between layers = **BLOCKER**
+- logic in `domain.objects/` must never reach into `access/`, `contract/`, or `domain.operations/`
+- logic in `domain.operations/` must not reference infrastructure concerns; they can can only leverage `infra/` adapters
+- logic in `access/` may use domain layers but must remain free of domain knowledge and business rules
+- logic in `infra/` must remain free of domain knowledge and business rules
 
 .examples
 
 ✅ positive
-```ts
+\`\`\`ts
 // contract/endpoints/sendInvoice.ts
-import { generateInvoice } from '@/logic/generateInvoice';
+import { generateInvoice } from '@/domain.operations/generateInvoice';
+import { invoiceDao } from '@/access/daos/invoiceDao';
 
-// logic/submitJob.ts
-import { Job } from '@/domain/objects/Job';
-import { jobDao } from '@/data/daos/jobDao';
+// access/daos/jobDao.ts
+import { Job } from '@/domain.objects/Job';
 
-// data/daos/jobDao.ts
-import { Job } from '@/domain/objects/Job';
-```
+// domain.operations/calculateTotal.ts
+import { LineItem } from '@/domain.objects/LineItem';
+\`\`\`
 
 ❌ negative
-```ts
-// domain/Customer.ts
-import { customerDao } from '@/data/daos/customerDao'; // ⛔ illegal upward import
-
-// domain/Invoice.ts
-import { calculateTotal } from '@/logic/calculateTotal'; // ⛔ direction violation
+\`\`\`ts
+// domain.objects/Customer.ts
+import { customerDao } from '@/access/daos/customerDao'; // ⛔ illegal upward import
 
-// data/sdkWrapper.ts
-import { dispatchFlow } from '@/logic/' // ⛔ bottom-up reference
-```
+// domain.operations/InvoiceOps.ts
+import { runFlow } from '@/contract/commands'; // ⛔ direction violation
 
+// access/svcs/sdkWrapper.ts
+import { dispatchFlow } from '@/contract/'; // ⛔ bottom-up reference
+\`\`\`

package/dist/logic/roles/mechanic/.briefs/criteria.practices/require.knowledge.externalized.md

@@ -0,0 +1,17 @@
+if using a tool dependency that is not already fully understood with internalized knowledge
+
+first, it is mandatory to externalize knowledge about that tool
+
+for example
+- what is it
+- when was it released
+- how much does it cost
+- how to use it
+
+- what are advantages and devantages? boons and banes?
+
+---
+
+research this always via a websearch first
+
+and always cite your sources

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.contract.inputs.nameargs/bad-practice/forbid.positional-args.md

@@ -0,0 +1,43 @@
+positional args are
+- hard to read
+- easy to break
+
+never use positional args if we can avoid them
+
+
+even in bash!
+
+
+---
+
+e.g., which one's easier to understand?
+
+
+```sh
+  # final attempt with fail_on_error=true (exits on hard failures, warns on timeout)
+  _try_start_port_forwarding "$instance_id" "$rds_endpoint" 60 true
+```
+
+
+vs
+
+```sh
+
+  # final attempt with fail_on_error=true (exits on hard failures, warns on timeout)
+  _try_start_port_forwarding \
+    instance_id="$instance_id" \
+    rds_endpoint="$rds_endpoint" \
+    timeout=60 \
+    fail_on_error=true
+```
+
+
+---
+
+
+
+  - Self-documenting: You can see what each parameter is at the call site
+  - Order-independent: Arguments can be passed in any order
+  - Easier to maintain: Adding new optional parameters won't break existing calls
+  - Validation: Each function validates required parameters
+  - Usage examples: Included in function headers

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.contract.inputs.nameargs/best-practice/require.namedargs.md

@@ -0,0 +1,6 @@
+always used named arguments on inputs
+
+they make it clear when reading what the arguments are used for
+
+they also make it possible to reorder arguments without breaking the contract (great for refactors, deprecations, renames, etc)
+