rhachet-roles-bhuild 0.14.1 → 0.14.3

package/dist/domain.operations/behavior/init/templates/3.2.distill.repros.experience._.v1.guard

@@ -0,0 +1,55 @@
+reviews:
+  self:
+    - slug: has-critical-paths-identified
+      say: |
+        double-check: did you identify the critical paths?
+
+        - are the happy paths marked as critical?
+        - for each critical path, is it clear why it must be frictionless?
+        - did you consider what would happen if each critical path failed?
+
+        for each critical path, verify pit of success:
+        - narrower inputs: can we constrain inputs to prevent misuse?
+        - convenient: can we infer inputs rather than require them?
+        - expressive: does it pull into inferred happy path, but allow expression of differences?
+        - failsafes: what happens when things go wrong? does it recover gracefully?
+        - failfasts: does it fail early and clearly when inputs are invalid?
+        - idempotency: can the operation be retried safely?
+
+        critical paths are the "golden paths" — the flows that most users take.
+        if these aren't frictionless, users will fail. fix the friction now.
+
+    - slug: has-ergonomics-reviewed
+      say: |
+        double-check: did you review the ergonomics?
+
+        for each input/output pair:
+        - does the input feel natural? if not, how can we simplify it?
+        - does the output feel natural? if not, what would be clearer?
+        - is there any friction? if so, how can we remove it?
+
+        pit of success principles:
+        - intuitive design: can users succeed without documentation?
+        - convenient: can we infer inputs rather than require them?
+        - expressive: does it pull into inferred happy path, but allow expression of differences?
+        - composable: can this be combined with other operations easily?
+        - lower trust contracts: do we validate at boundaries?
+        - deeper behavior: do we handle edge cases gracefully?
+
+        awkward inputs and outputs are bugs. fix them now, before implementation.
+        every friction point you leave becomes a support ticket later.
+
+    - slug: has-play-test-convention
+      say: |
+        double-check: are journey tests named correctly?
+
+        journey test files should use `.play.test.ts` suffix:
+        - `feature.play.test.ts` — journey test
+        - `feature.play.integration.test.ts` — if repo requires integration runner
+        - `feature.play.acceptance.test.ts` — if repo requires acceptance runner
+
+        this distinguishes journey tests (step-by-step user experience tests)
+        from unit tests (`.test.ts`) and integration tests (`.integration.test.ts`).
+
+        if the repo doesn't support `.play.test.ts` directly, plan to use
+        `.play.integration.test.ts` or `.play.acceptance.test.ts` instead.

package/dist/domain.operations/behavior/init/templates/3.2.distill.repros.experience._.v1.stone

@@ -14,12 +14,118 @@ for each user experience in the vision, define how it will be reproduced in test
 
 ---
 
+## journey test sketches
+
+for each experience, sketch the journey test with full BDD structure.
+
+### structure
+
+journey tests use `given/when/then` blocks with `[tN]` labels:
+
+```
+given('[case1] {scenario description}')
+  when('[t0] before any changes')
+    then('{precondition holds}')
+    then('input/output matches snapshot')  ← snapshot!
+  when('[t1] {first action}')
+    then('{expected outcome}')
+    then('input/output matches snapshot')  ← snapshot!
+  when('[t2] {second action}')
+    then('{expected outcome}')
+    then('input/output matches snapshot')  ← snapshot!
+```
+
+### step table
+
+for each journey, create a step table:
+
+| step | action | user sees |
+|------|--------|-----------|
+| t0 | before any changes | {describe what user sees} |
+| t1 | {first action} | {describe what user sees} |
+| t2 | {second action} | {describe what user sees} |
+
+### input/output pairs
+
+for each step, document:
+- **input**: what the caller provides
+- **output**: what the caller receives (terminal, screen, response)
+
+example (CLI):
+```
+#### t1 success case (snapshot target)
+$ rhx init.behavior --name my-feature
+
+init.behavior
+
+created .behavior/v2024_03_12.my-feature/
+   ├─ 0.wish.md
+   └─ ... (more files)
+```
+
+example (SDK):
+```
+#### t1 success case (snapshot target)
+// input
+const customer = await sdk.createCustomer({ email: 'test@example.com' });
+
+// output
+{ id: 'cus_abc123', email: 'test@example.com', status: 'active' }
+```
+
+### snapshot coverage plan
+
+mark which outputs need `.snap` files:
+
+- [ ] t0 before state → `.snap`
+- [ ] t1 success input/output → `.snap`
+- [ ] t1 error input/output → `.snap`
+- [ ] t2 after state → `.snap`
+
+### file convention
+
+journey test files use `.play.test.ts` suffix:
+- `feature.play.test.ts` — journey test
+- `feature.play.integration.test.ts` — journey test run as integration
+- `feature.play.acceptance.test.ts` — journey test run as acceptance
+
+this distinguishes journey tests from unit tests (`.test.ts`).
+
+---
+
+## critical paths
+
+identify the happy paths that must be frictionless.
+
+| critical path | description | why critical |
+|---------------|-------------|--------------|
+| {path 1} | {what user does} | {why this must work} |
+| {path 2} | {what user does} | {why this must work} |
+
+critical paths are the "golden paths" — the main flows that most users take.
+if these fail or have friction, the product fails.
+
+---
+
+## ergonomics review
+
+for each input/output pair, review:
+- does the input feel natural? is it what the user would expect to provide?
+- does the output feel natural? is it what the user would expect to see?
+- is there friction? what could be smoother?
+
+| journey | input ergonomics | output ergonomics | friction notes |
+|---------|------------------|-------------------|----------------|
+| {journey 1} | {natural / awkward} | {natural / awkward} | {any friction} |
+
+---
+
 ## reproduction feasibility
 
 for each experience, confirm it can be reproduced:
 - what test utilities are available?
 - what setup is required?
-- show a concrete test sketch
+- show a concrete test sketch (use journey structure above)
 
 ---
 

package/dist/domain.operations/behavior/init/templates/5.2.evaluation.v1.guard

@@ -0,0 +1,51 @@
+reviews:
+  self:
+    - slug: has-complete-implementation-record
+      say: |
+        double-check: did you document everything that was implemented?
+
+        - is every file change recorded in the filediff tree?
+        - is every codepath change recorded in the codepath tree?
+        - is every test recorded in the test coverage section?
+
+        silent changes are dangerous. if it's not documented, it didn't happen.
+        go back and check git diff against origin/main.
+
+    - slug: has-divergence-analysis
+      say: |
+        double-check: did you find all the divergences?
+
+        compare blueprint vs implementation for each section:
+        - summary: does the actual match the declared?
+        - filediff: are all files accounted for?
+        - codepath: are all codepaths accounted for?
+        - test coverage: are all tests accounted for?
+
+        be skeptical. assume you missed something.
+        what would a hostile reviewer find that you overlooked?
+
+    - slug: has-divergence-addressed
+      say: |
+        double-check: did you address each divergence properly?
+
+        for each divergence:
+        - if repaired: did you actually make the fix? is it visible in git?
+        - if backed up: is the rationale convincing? would a skeptic accept it?
+
+        question each backup skeptically:
+        - is this truly an improvement, or just laziness?
+        - did we just not want to do the work the blueprint required?
+        - could this divergence cause problems later?
+
+        a backup without strong rationale is a defect. repair it instead.
+
+    - slug: has-no-silent-scope-creep
+      say: |
+        double-check: did any scope creep into the implementation?
+
+        - did you add features not in the blueprint?
+        - did you change things "while you were in there"?
+        - did you refactor code unrelated to the wish?
+
+        scope creep is a divergence. document it and address it.
+        enumerate each with [repair] or [backup] decision in the review file.

package/dist/domain.operations/behavior/init/templates/5.2.evaluation.v1.stone

@@ -0,0 +1,88 @@
+evaluate what was implemented against the blueprint
+
+.what = articulate exactly what was implemented, then check for divergences from blueprint.
+
+.why = the blueprint declared what the execution would adhere to.
+- divergences may be intentional improvements or accidental drift
+- each divergence must be either repaired or backed up with rationale
+- this gate prevents silent deviations from approved design
+
+---
+
+reference the blueprint:
+- $BEHAVIOR_DIR_REL/3.3.1.blueprint.product.v1.i1.md
+
+---
+
+## summary (as implemented)
+
+state what was actually built. mirror the blueprint summary structure.
+
+---
+
+## filediff tree (as implemented)
+
+include a treestruct of filediffs that were actually made.
+
+**legend:**
+- `[+] created` — file created
+- `[~] updated` — file updated
+- `[-] deleted` — file deleted
+
+---
+
+## codepath tree (as implemented)
+
+include a treestruct of codepaths that were actually implemented.
+
+**legend:**
+- `[+]` created — codepath created
+- `[~]` updated — codepath updated
+- `[○]` retained — codepath retained
+- `[-]` deleted — codepath deleted
+- `[←]` reused — codepath reused from elsewhere
+- `[→]` ejected — codepath decomposed for reuse
+
+---
+
+## test coverage (as implemented)
+
+document what tests were actually written:
+- unit tests
+- integration tests
+- acceptance tests
+
+---
+
+## divergence analysis
+
+for each section (summary, filediff, codepath, test coverage), compare:
+- what the blueprint declared
+- what was actually implemented
+
+### divergences found
+
+| section | blueprint declared | actual implemented | divergence type |
+|---------|-------------------|-------------------|-----------------|
+| ... | ... | ... | added/removed/changed |
+
+### divergence resolution
+
+for each divergence, you must either:
+
+**repair** — fix the implementation to match the blueprint:
+- what needs to change to match blueprint?
+- make the change, then update the "as implemented" section above
+
+**backup** — document why the divergence is acceptable:
+- why did the implementation diverge?
+- why is the divergence better than the blueprint?
+- should the blueprint be updated for future reference?
+
+| divergence | resolution | rationale |
+|------------|------------|-----------|
+| ... | repair/backup | ... |
+
+---
+
+emit into $BEHAVIOR_DIR_REL/5.2.evaluation.v1.i1.md

package/dist/domain.operations/behavior/init/templates/5.3.verification.v1.guard

@@ -52,3 +52,72 @@ reviews:
 
         to "fix tests" via changed intent is not a fix — it is at worst
         malicious deception, at best reckless negligence. unacceptable.
+
+    - slug: has-journey-tests-from-repros
+      say: |
+        double-check: did you implement each journey sketched in repros?
+
+        look back at the repros artifact:
+        - $BEHAVIOR_DIR_REL/3.2.distill.repros.experience.*.md
+
+        for each journey test sketch in repros:
+        - is there a test file for it?
+        - does the test follow the BDD given/when/then structure?
+        - does each `when([tN])` step exist?
+
+        if any journey was planned but not implemented, go back and add it.
+
+    - slug: has-snapshot-coverage
+      say: |
+        double-check: do snapshots capture input/output for caller visibility?
+
+        for each journey test:
+        - does it have `.toMatchSnapshot()` or equivalent assertions?
+        - does the snapshot show what the caller would actually see?
+        - for CLI: is stdout/stderr captured?
+        - for UI: are screens captured?
+        - for SDK: are responses captured?
+
+        snapshots let reviewers see the actual output without the need to run the code.
+        if snapshots are absent, the reviewer can't verify the user experience.
+
+    - slug: has-critical-paths-frictionless
+      say: |
+        double-check: are the critical paths frictionless in practice?
+
+        look back at the repros artifact for critical paths:
+        - $BEHAVIOR_DIR_REL/3.2.distill.repros.experience.*.md
+
+        for each critical path:
+        - run through it manually — is it smooth?
+        - are there unexpected errors?
+        - does it feel effortless to the user?
+
+        critical paths must "just work." if there's friction, fix it now.
+
+    - slug: has-ergonomics-validated
+      say: |
+        double-check: does the actual input/output match what felt right at repros?
+
+        compare the implemented input/output to what was sketched in repros:
+        - does the actual input match the planned input?
+        - does the actual output match the planned output?
+        - did the design change between repros and implementation?
+
+        if the ergonomics drifted, either:
+        - update repros to reflect the better design, or
+        - fix the implementation to match the planned ergonomics
+
+    - slug: has-play-test-convention
+      say: |
+        double-check: are journey test files named correctly?
+
+        journey tests should use `.play.test.ts` suffix:
+        - `feature.play.test.ts` — journey test
+        - `feature.play.integration.test.ts` — if repo requires integration runner
+        - `feature.play.acceptance.test.ts` — if repo requires acceptance runner
+
+        verify:
+        - are journey tests in the right location?
+        - do they have the `.play.` suffix?
+        - if not supported, is the fallback convention used?

package/dist/domain.operations/behavior/init/templates/5.3.verification.v1.stone

@@ -36,6 +36,7 @@ reference the below for full context
 - $BEHAVIOR_DIR_REL/0.wish.md
 - $BEHAVIOR_DIR_REL/1.vision.md
 - $BEHAVIOR_DIR_REL/2.1.criteria.blackbox.md (if declared)
+- $BEHAVIOR_DIR_REL/3.2.distill.repros.experience.*.md (if declared) ← **repros artifact**
 
 ---
 
@@ -51,11 +52,14 @@ this is your roadmap. emit it first, then work through it step by step.
 ```
 ## verification checklist
 
-### behavior coverage
-| behavior (from wish/vision) | test file | status |
-|-----------------------------|-----------|--------|
-| {behavior 1}                | {path}    | ⏳     |
-| {behavior 2}                | {path}    | ⏳     |
+### behavior coverage (with reference to repros)
+
+for each journey sketched in repros, verify it was implemented with snapshots.
+
+| journey (from repros) | test file | snapshots? | critical path? | ergonomics ok? | status |
+|-----------------------|-----------|------------|----------------|----------------|--------|
+| {journey 1}           | {path}    | ✓ / ✗      | ✓ frictionless / needs work | ✓ natural / needs work | ⏳ |
+| {journey 2}           | {path}    | ✓ / ✗      | ✓ frictionless / needs work | ✓ natural / needs work | ⏳ |
 ...
 
 ### zero skips verified

package/dist/domain.operations/behavior/init/templates/5.5.playtest.v1.guard

@@ -24,5 +24,36 @@ reviews:
         - what inputs are unusual but valid?
         - are boundaries tested?
 
+    - slug: has-acceptance-test-citations
+      say: |
+        coverage check: cite the acceptance test for each playtest step.
+
+        for each step in the playtest:
+        - which acceptance test file verifies this behavior?
+        - which specific test case (given/when/then) covers it?
+        - cite the exact file path and test name
+
+        if a step lacks acceptance test coverage:
+        - is this a gap that needs a new test?
+        - or is this behavior untestable via automation?
+
+        the playtest and acceptance tests should align. cite the proof.
+
+    - slug: has-self-run-verification
+      say: |
+        dogfood check: did you run the playtest yourself?
+
+        before you hand off to the foreman, run every step yourself:
+        - follow each instruction exactly as written
+        - verify each expected outcome matches reality
+        - note any friction, confusion, or absent context
+
+        if you found issues while you ran it:
+        - did you fix the instructions?
+        - did you update expected outcomes?
+        - is the playtest now accurate to what you observed?
+
+        the foreman deserves a playtest that works. prove it works by self-test first.
+
 judges:
   - npx rhachet run --repo bhrain --skill route.stone.judge --mechanism approved? --stone $stone --route $route

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-bhuild",
   "author": "ehmpathy",
   "description": "roles for building resilient systems, via rhachet",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "repository": "ehmpathy/rhachet-roles-bhuild",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-bhuild",
   "keywords": [
@@ -89,11 +89,11 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.37.14",
+    "rhachet": "1.37.15",
     "rhachet-brains-anthropic": "0.3.3",
     "rhachet-roles-bhrain": "0.18.1",
     "rhachet-roles-bhuild": "link:.",
-    "rhachet-roles-ehmpathy": "1.27.12",
+    "rhachet-roles-ehmpathy": "1.27.13",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",
     "typescript": "5.4.5",