rhachet-roles-ehmpathy 1.15.15 → 1.15.17

package/dist/domain.roles/mechanic/briefs/practices/code.test/frames.behavior/howto.write-bdd.[lesson].pt2.md

@@ -0,0 +1,222 @@
+# how to write bdd-style acceptance tests
+
+## structure
+
+use `given`, `when`, `then` from `test-fns` to structure tests:
+
+```ts
+import { given, when, then, useBeforeAll } from 'test-fns';
+
+describe('featureName', () => {
+  given('[case1] scenario description', () => {
+    when('[t0] before any changes', () => {
+      then('precondition holds', async () => { ... });
+      then('another precondition holds', async () => { ... });
+    });
+
+    when('[t1] target operation is executed', () => {
+      then('expected outcome', async () => { ... });
+    });
+
+    when('[t2] alternate operation is executed', () => {
+      then('alternate outcome', async () => { ... });
+    });
+  });
+});
+```
+
+---
+
+## labels
+
+### `[caseN]` for given blocks
+
+each `given` block should have a unique case label:
+
+```ts
+given('[case1] valid inputs', () => { ... });
+given('[case2] invalid inputs', () => { ... });
+given('[case3] edge case scenario', () => { ... });
+```
+
+### `[tN]` for when blocks
+
+each `when` block should have a time index label:
+
+- `[t0]` = precondition checks / before any changes
+- `[t1]` = first target operation
+- `[t2]` = second target operation
+- etc.
+
+```ts
+given('[case1] prose-author example repo', () => {
+  when('[t0] before any changes', () => {
+    then('rules glob matches 2 files', ...);
+    then('chapters glob matches 3 files', ...);
+  });
+
+  when('[t1] stepReview on clean chapter', () => {
+    then('review contains no blockers', ...);
+  });
+
+  when('[t2] stepReview on dirty chapter', () => {
+    then('review contains blockers', ...);
+  });
+});
+```
+
+---
+
+## principles
+
+### consolidate related tests
+
+don't split related scenarios across multiple `given` blocks:
+
+```ts
+// ❌ bad - fragmented
+given('[case8] prose-author rule enumeration', () => { ... });
+given('[case9] prose-author chapter enumeration', () => { ... });
+given('[case10] prose-author review works', () => { ... });
+
+// ✅ good - consolidated
+given('[case8] prose-author example repo', () => {
+  when('[t0] before any changes', () => {
+    then('rules glob matches', ...);
+    then('chapters glob matches', ...);
+  });
+  when('[t1] stepReview on clean chapter', () => { ... });
+  when('[t2] stepReview on dirty chapter', () => { ... });
+});
+```
+
+### when describes state/time, not action
+
+```ts
+// ❌ bad - describes action
+when('[t0] assets are checked', () => { ... });
+
+// ✅ good - describes state/time
+when('[t0] before any changes', () => { ... });
+```
+
+### use afterEach for cleanup
+
+```ts
+// ❌ bad - inline cleanup
+then('creates output file', async () => {
+  const result = await doThing();
+  await fs.rm(outputPath); // cleanup inside then
+  expect(result).toBeDefined();
+});
+
+// ✅ good - afterEach cleanup
+when('[t1] operation runs', () => {
+  const outputPath = path.join(os.tmpdir(), 'output.md');
+  afterEach(async () => fs.rm(outputPath, { force: true }));
+
+  then('creates output file', async () => {
+    const result = await doThing();
+    expect(result).toBeDefined();
+  });
+});
+```
+
+### preconditions shouldn't expect errors
+
+```ts
+// ❌ bad - precondition expects error then checks it's not a validation error
+then('does not throw validation errors', async () => {
+  const error = await getError(doThing());
+  expect(error.message).not.toContain('validation');
+});
+
+// ✅ good - precondition checks assets directly
+then('rules glob matches 2 files', async () => {
+  const files = await enumFiles({ glob: 'rules/*.md' });
+  expect(files).toHaveLength(2);
+});
+```
+
+### use useBeforeAll for shared setup
+
+```ts
+given('[case1] scenario with shared setup', () => {
+  const scene = useBeforeAll(async () => {
+    const entity = await createEntity();
+    return { entity };
+  });
+
+  when('[t1] operation runs', () => {
+    then('uses shared entity', async () => {
+      const result = await doThing({ id: scene.entity.id });
+      expect(result).toBeDefined();
+    });
+  });
+});
+```
+
+---
+
+## complete example
+
+```ts
+import { given, when, then, useBeforeAll } from 'test-fns';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+describe('stepReview', () => {
+  given('[case1] prose-author example repo', () => {
+    when('[t0] before any changes', () => {
+      then('rules glob matches 2 prose style rules', async () => {
+        const ruleFiles = await enumFilesFromGlob({
+          glob: '.agent/**/rules/*.md',
+          cwd: ASSETS_PROSE,
+        });
+        expect(ruleFiles).toHaveLength(2);
+      });
+
+      then('chapters glob matches 3 chapters', async () => {
+        const chapterFiles = await enumFilesFromGlob({
+          glob: 'chapters/*.md',
+          cwd: ASSETS_PROSE,
+        });
+        expect(chapterFiles).toHaveLength(3);
+      });
+    });
+
+    when('[t1] stepReview on chapter2.fixed.md', () => {
+      const outputPath = path.join(os.tmpdir(), 'review-fixed.md');
+      afterEach(async () => fs.rm(outputPath, { force: true }));
+
+      then('review contains no blockers', async () => {
+        const result = await stepReview({
+          rules: '.agent/**/rules/*.md',
+          paths: 'chapters/chapter2.fixed.md',
+          output: outputPath,
+          mode: 'hard',
+          cwd: ASSETS_PROSE,
+        });
+        expect(result.review.formatted.toLowerCase()).not.toContain('blocker');
+      });
+    });
+
+    when('[t2] stepReview on chapter2.md', () => {
+      const outputPath = path.join(os.tmpdir(), 'review-unfixed.md');
+      afterEach(async () => fs.rm(outputPath, { force: true }));
+
+      then('review contains blockers for gerund violations', async () => {
+        const result = await stepReview({
+          rules: '.agent/**/rules/*.md',
+          paths: 'chapters/chapter2.md',
+          output: outputPath,
+          mode: 'hard',
+          cwd: ASSETS_PROSE,
+        });
+        expect(result.review.formatted.toLowerCase()).toContain('blocker');
+      });
+    });
+  });
+});
+```

package/dist/domain.roles/mechanic/briefs/practices/work.flow/diagnose/howto.bisect.[lesson].md

@@ -0,0 +1,74 @@
+# howto: diagnose via bisection
+
+## .what
+
+use binary search (bisection) to isolate the root cause of a defect in O(log n) steps instead of O(n)
+
+## .why
+
+- linear search through suspects wastes time
+- bisection cuts the search space in half with each test
+- works for code changes, data inputs, config options, and time ranges
+- essential skill for debugging regressions and intermittent failures
+
+## .how
+
+### the pattern
+
+1. define the search space (lines, inputs, configs, changes)
+2. find a known-good state and a known-bad state
+3. test the midpoint
+4. if midpoint is good → defect is in the second half
+5. if midpoint is bad → defect is in the first half
+6. repeat until you find the exact boundary
+
+### code bisection (for logic errors)
+
+when a function produces wrong output:
+
+```ts
+// suspect: 10 lines of logic
+const result = complexTransform(input);
+
+// bisect: comment out bottom half, test
+// if still broken → defect in top half
+// if fixed → defect in bottom half
+// repeat until isolated to 1-2 lines
+```
+
+### input bisection (for data issues)
+
+when processing fails on large input:
+
+```ts
+// 1000 records fail; which one causes it?
+const midpoint = Math.floor(records.length / 2);
+const firstHalf = records.slice(0, midpoint);
+const secondHalf = records.slice(midpoint);
+
+// test each half separately
+// defect is in the half that fails
+// repeat until you find the single bad record
+```
+
+### config bisection (for env issues)
+
+when config changes break behavior:
+
+1. list all config differences between working and broken
+2. apply half the changes
+3. test → narrow to the half that breaks
+4. repeat until isolated to single config key
+
+## .when to use
+
+- regression appeared but unclear which change caused it
+- feature works with small data but fails with large data
+- behavior differs between environments
+- any scenario with a "it used to work" vs "now it's broken" boundary
+
+## .key insight
+
+> the power of bisection: 1000 suspects → 10 tests max
+
+always prefer structured bisection over random guessing or linear elimination

package/dist/domain.roles/mechanic/inits/init.claude.permissions.jsonc

@@ -11,7 +11,9 @@
     "deny": [
       // git write operations - require explicit user request for audit trail
       "Bash(git commit:*)",
-      "Bash(git add:*)",
+      "Bash(git add .)",
+      "Bash(git add -A:*)",
+      "Bash(git add --all:*)",
       "Bash(git stash:*)",
       "Bash(git checkout:*)",
       "Bash(git branch -d:*)",
@@ -24,6 +26,10 @@
       "Bash(git reflog delete:*)",
       "Bash(git config:*)",
 
+      // git mv/rm - use mvsafe.sh and rmsafe.sh instead (repo-constrained)
+      "Bash(git mv:*)",
+      "Bash(git rm:*)",
+
       // "anywrite" commands - CRITICAL SECURITY RISK
       //
       // unlike Claude's native Edit/Write tools which are scoped to the repo,
@@ -141,10 +147,6 @@
       "Bash(mkdir:*)",
       "Bash(pwd)",
 
-      // git mv/rm are safe - constrained to repo, all changes revertable
-      "Bash(git mv:*)",
-      "Bash(git rm:*)",
-
       // git read-only - all have no write variants
       "Bash(git log:*)",
       "Bash(git status:*)",
@@ -162,6 +164,12 @@
       // cpsafe - safe file copy within git repo (source must be git-tracked)
       "Bash(.agent/repo=ehmpathy/role=mechanic/skills/.skills/claude.tools/cpsafe.sh:*)",
 
+      // mvsafe - safe file move within git repo
+      "Bash(.agent/repo=ehmpathy/role=mechanic/skills/.skills/claude.tools/mvsafe.sh:*)",
+
+      // rmsafe - safe file removal within git repo
+      "Bash(.agent/repo=ehmpathy/role=mechanic/skills/.skills/claude.tools/rmsafe.sh:*)",
+
       // npm read operations
       "Bash(npm view:*)",
       "Bash(npm list:*)",
@@ -209,6 +217,9 @@
       "Bash(RESNAP=true THOROUGH=true npm run test:integration:*)",
       "Bash(RESNAP=true THOROUGH=true npm run test:acceptance:*)",
 
+      // test list operation
+      "Bash(npx jest --listTests:*)",
+
       // fix operations
       "Bash(npm run fix:*)",
       "Bash(npm run fix:format:*)",

package/dist/domain.roles/mechanic/skills/claude.tools/mvsafe.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = safe file move within git repo
+#
+# .why  = enables file moving without:
+#         - touching files outside the repo
+#         - accidental path traversal attacks
+#
+#         this is a controlled alternative to raw mv, which is
+#         denied in permissions due to security risks.
+#
+# usage:
+#   mvsafe.sh --src "path/to/source" --dest "path/to/dest"
+#
+# guarantee:
+#   - source must be within repo
+#   - dest must be within repo
+#   - creates parent directories if needed
+#   - fail-fast on errors
+######################################################################
+set -euo pipefail
+
+# parse named arguments
+SRC=""
+DEST=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --src)
+      SRC="$2"
+      shift 2
+      ;;
+    --dest)
+      DEST="$2"
+      shift 2
+      ;;
+    *)
+      echo "unknown argument: $1"
+      echo "usage: mvsafe.sh --src 'source' --dest 'destination'"
+      exit 1
+      ;;
+  esac
+done
+
+# validate required args
+if [[ -z "$SRC" ]]; then
+  echo "error: --src is required"
+  exit 1
+fi
+
+if [[ -z "$DEST" ]]; then
+  echo "error: --dest is required"
+  exit 1
+fi
+
+# ensure we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "error: not in a git repository"
+  exit 1
+fi
+
+# get repo root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# resolve absolute paths
+SRC_ABS=$(realpath -m "$SRC")
+DEST_ABS=$(realpath -m "$DEST")
+
+# validate source is within repo
+if [[ "$SRC_ABS" != "$REPO_ROOT"* ]]; then
+  echo "error: source must be within the git repository"
+  echo "  repo root: $REPO_ROOT"
+  echo "  source:    $SRC_ABS"
+  exit 1
+fi
+
+# validate dest is within repo
+if [[ "$DEST_ABS" != "$REPO_ROOT"* ]]; then
+  echo "error: destination must be within the git repository"
+  echo "  repo root: $REPO_ROOT"
+  echo "  dest:      $DEST_ABS"
+  exit 1
+fi
+
+# validate source exists
+if [[ ! -e "$SRC_ABS" ]]; then
+  echo "error: source does not exist: $SRC"
+  exit 1
+fi
+
+# create parent directories if needed
+DEST_DIR=$(dirname "$DEST_ABS")
+if [[ ! -d "$DEST_DIR" ]]; then
+  echo "creating directory: $DEST_DIR"
+  mkdir -p "$DEST_DIR"
+fi
+
+# perform the move
+mv "$SRC_ABS" "$DEST_ABS"
+
+SRC_REL="${SRC_ABS#$REPO_ROOT/}"
+DEST_REL="${DEST_ABS#$REPO_ROOT/}"
+echo "moved: $SRC_REL -> $DEST_REL"

package/dist/domain.roles/mechanic/skills/claude.tools/rmsafe.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = safe file removal within git repo
+#
+# .why  = enables file deletion without:
+#         - touching files outside the repo
+#         - accidental path traversal attacks
+#
+#         this is a controlled alternative to raw rm, which is
+#         denied in permissions due to security risks.
+#
+# usage:
+#   rmsafe.sh --path "path/to/file"
+#   rmsafe.sh --path "path/to/dir" --recursive
+#
+# guarantee:
+#   - path must be within repo
+#   - requires --recursive for directories
+#   - fail-fast on errors
+######################################################################
+set -euo pipefail
+
+# parse named arguments
+TARGET=""
+RECURSIVE=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --path)
+      TARGET="$2"
+      shift 2
+      ;;
+    --recursive|-r)
+      RECURSIVE=true
+      shift
+      ;;
+    *)
+      echo "unknown argument: $1"
+      echo "usage: rmsafe.sh --path 'target' [--recursive]"
+      exit 1
+      ;;
+  esac
+done
+
+# validate required args
+if [[ -z "$TARGET" ]]; then
+  echo "error: --path is required"
+  exit 1
+fi
+
+# ensure we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "error: not in a git repository"
+  exit 1
+fi
+
+# get repo root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# resolve absolute path
+TARGET_ABS=$(realpath -m "$TARGET")
+
+# validate target is within repo
+if [[ "$TARGET_ABS" != "$REPO_ROOT"* ]]; then
+  echo "error: path must be within the git repository"
+  echo "  repo root: $REPO_ROOT"
+  echo "  path:      $TARGET_ABS"
+  exit 1
+fi
+
+# prevent deleting repo root itself
+if [[ "$TARGET_ABS" == "$REPO_ROOT" ]]; then
+  echo "error: cannot delete the repository root"
+  exit 1
+fi
+
+# validate target exists
+if [[ ! -e "$TARGET_ABS" ]]; then
+  echo "error: path does not exist: $TARGET"
+  exit 1
+fi
+
+# check if directory and require --recursive
+if [[ -d "$TARGET_ABS" ]] && [[ "$RECURSIVE" != true ]]; then
+  echo "error: target is a directory, use --recursive to delete"
+  exit 1
+fi
+
+# perform the removal
+if [[ "$RECURSIVE" == true ]]; then
+  rm -rf "$TARGET_ABS"
+else
+  rm "$TARGET_ABS"
+fi
+
+TARGET_REL="${TARGET_ABS#$REPO_ROOT/}"
+echo "removed: $TARGET_REL"

package/dist/domain.roles/mechanic/skills/gh.workflow.logs.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = fetch logs from the latest test workflow run on current branch
+#
+# .why  = enables quick access to CI logs without leaving the terminal
+#         - diagnose failing tests faster
+#         - review workflow output during development
+#         - avoid context-switching to browser
+#
+# usage:
+#   gh.workflow.logs.sh --workflow "test"            # failed logs from latest test run
+#   gh.workflow.logs.sh --workflow "ci" --full       # show full logs (not just failed)
+#   gh.workflow.logs.sh --run-id 12345678            # view specific run by id
+#   gh.workflow.logs.sh --workflow "test" --watch    # watch in-progress run
+#   gh.workflow.logs.sh --workflow "test" --web      # open in browser instead
+#
+# guarantee:
+#   - uses gh cli (must be authenticated)
+#   - defaults to current branch
+#   - shows most recent run if no run-id specified
+#   - fail-fast on errors
+######################################################################
+set -euo pipefail
+
+# parse named arguments
+WORKFLOW=""
+RUN_ID=""
+FULL_LOGS=false
+WATCH_MODE=false
+WEB_MODE=false
+BRANCH=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --workflow|-w)
+      WORKFLOW="$2"
+      shift 2
+      ;;
+    --run-id|-r)
+      RUN_ID="$2"
+      shift 2
+      ;;
+    --full)
+      FULL_LOGS=true
+      shift
+      ;;
+    --watch)
+      WATCH_MODE=true
+      shift
+      ;;
+    --web)
+      WEB_MODE=true
+      shift
+      ;;
+    --branch|-b)
+      BRANCH="$2"
+      shift 2
+      ;;
+    --help|-h)
+      echo "usage: gh.workflow.logs.sh --workflow <name> [options]"
+      echo ""
+      echo "required:"
+      echo "  --workflow, -w <name>   workflow name (e.g., 'test', 'ci')"
+      echo ""
+      echo "options:"
+      echo "  --run-id, -r <id>       view specific run by id (skips workflow lookup)"
+      echo "  --full                  show full logs (default: failed only)"
+      echo "  --watch                 watch in-progress run"
+      echo "  --web                   open in browser instead of terminal"
+      echo "  --branch, -b <name>     use specific branch (default: current)"
+      echo "  --help, -h              show this help"
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1"
+      echo "run with --help for usage"
+      exit 1
+      ;;
+  esac
+done
+
+# require workflow unless run-id specified
+if [[ -z "$WORKFLOW" && -z "$RUN_ID" ]]; then
+  echo "error: --workflow is required"
+  echo "usage: gh.workflow.logs.sh --workflow <name> [options]"
+  echo "run with --help for more info"
+  exit 1
+fi
+
+# ensure gh cli is available
+if ! command -v gh &> /dev/null; then
+  echo "error: gh cli is not installed"
+  echo "install: https://cli.github.com/"
+  exit 1
+fi
+
+# ensure we're authenticated
+if ! gh auth status &> /dev/null; then
+  echo "error: not authenticated with gh cli"
+  echo "run: gh auth login"
+  exit 1
+fi
+
+# ensure we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "error: not in a git repository"
+  exit 1
+fi
+
+# get current branch if not specified
+if [[ -z "$BRANCH" ]]; then
+  BRANCH=$(git branch --show-current)
+  if [[ -z "$BRANCH" ]]; then
+    echo "error: could not determine current branch (detached HEAD?)"
+    exit 1
+  fi
+fi
+
+echo ":: branch: $BRANCH"
+
+# if run-id specified, use it directly
+if [[ -n "$RUN_ID" ]]; then
+  echo ":: run-id: $RUN_ID"
+else
+  # build gh run list command
+  LIST_CMD="gh run list --branch $BRANCH --limit 1 --json databaseId,workflowName,status,conclusion,createdAt"
+
+  if [[ -n "$WORKFLOW" ]]; then
+    LIST_CMD="$LIST_CMD --workflow $WORKFLOW"
+  fi
+
+  # get latest run
+  RUNS_JSON=$(eval "$LIST_CMD")
+
+  if [[ "$RUNS_JSON" == "[]" ]]; then
+    echo ""
+    echo "no workflow runs found for branch: $BRANCH"
+    if [[ -n "$WORKFLOW" ]]; then
+      echo "with workflow filter: $WORKFLOW"
+    fi
+    echo ""
+    echo "available workflows:"
+    gh workflow list
+    exit 1
+  fi
+
+  # extract run info
+  RUN_ID=$(echo "$RUNS_JSON" | jq -r '.[0].databaseId')
+  WORKFLOW_NAME=$(echo "$RUNS_JSON" | jq -r '.[0].workflowName')
+  STATUS=$(echo "$RUNS_JSON" | jq -r '.[0].status')
+  CONCLUSION=$(echo "$RUNS_JSON" | jq -r '.[0].conclusion')
+  CREATED_AT=$(echo "$RUNS_JSON" | jq -r '.[0].createdAt')
+
+  echo ":: workflow: $WORKFLOW_NAME"
+  echo ":: run-id: $RUN_ID"
+  echo ":: status: $STATUS"
+  if [[ "$CONCLUSION" != "null" ]]; then
+    echo ":: conclusion: $CONCLUSION"
+  fi
+  echo ":: created: $CREATED_AT"
+fi
+
+echo ""
+
+# handle watch mode
+if [[ "$WATCH_MODE" == "true" ]]; then
+  echo ":: watching run $RUN_ID ..."
+  gh run watch "$RUN_ID"
+  exit 0
+fi
+
+# handle web mode
+if [[ "$WEB_MODE" == "true" ]]; then
+  echo ":: opening in browser ..."
+  gh run view "$RUN_ID" --web
+  exit 0
+fi
+
+# get repo info for api calls
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+
+# get jobs for this run
+JOBS_JSON=$(gh api --method GET "repos/$REPO/actions/runs/$RUN_ID/jobs" -q '.jobs')
+
+# view logs
+if [[ "$FULL_LOGS" == "true" ]]; then
+  echo ":: fetching full logs ..."
+  echo ""
+  # get all job ids and fetch logs for each
+  JOB_IDS=$(echo "$JOBS_JSON" | jq -r '.[].id')
+  for JOB_ID in $JOB_IDS; do
+    JOB_NAME=$(echo "$JOBS_JSON" | jq -r ".[] | select(.id == $JOB_ID) | .name")
+    echo "=== $JOB_NAME ==="
+    gh api --method GET "repos/$REPO/actions/jobs/$JOB_ID/logs"
+    echo ""
+  done
+else
+  echo ":: fetching failed job logs ..."
+  echo ""
+  # get only failed job ids
+  FAILED_JOB_IDS=$(echo "$JOBS_JSON" | jq -r '.[] | select(.conclusion == "failure") | .id')
+  if [[ -z "$FAILED_JOB_IDS" ]]; then
+    echo "no failed jobs found"
+    exit 0
+  fi
+  for JOB_ID in $FAILED_JOB_IDS; do
+    JOB_NAME=$(echo "$JOBS_JSON" | jq -r ".[] | select(.id == $JOB_ID) | .name")
+    echo "=== $JOB_NAME (failed) ==="
+    # fetch logs and filter to show failures
+    gh api --method GET "repos/$REPO/actions/jobs/$JOB_ID/logs" | grep -E "(FAIL |✕|Error:|Cannot find|##\[error\])" | head -100
+    echo ""
+  done
+fi

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.15.15",
+  "version": "1.15.17",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [