Merge remote-tracking branch 'origin/main' into han-communication

Author: mxriverlynn

.github/dependabot.yml

@@ -0,0 +1,35 @@
+version: 2
+
+# One monthly pull request bundles updates across all three ecosystems (npm,
+# GitHub Actions, pre-commit) via a multi-ecosystem group. Each ecosystem holds
+# a newly published version for 30 days before proposing it (cooldown), to lower
+# supply-chain risk from fresh or compromised releases. Cooldown does not apply
+# to security updates, so enabling Dependabot security updates in the repository
+# settings still lands those immediately.
+multi-ecosystem-groups:
+  dev-tooling:
+    schedule:
+      interval: monthly
+
+updates:
+  # npm devDependencies: prek, Prettier, Bats.
+  - package-ecosystem: npm
+    directory: "/"
+    multi-ecosystem-group: dev-tooling
+    cooldown:
+      default-days: 30
+
+  # GitHub Actions used by the CI workflows.
+  - package-ecosystem: github-actions
+    directory: "/"
+    multi-ecosystem-group: dev-tooling
+    cooldown:
+      default-days: 30
+
+  # pre-commit hook revisions in .pre-commit-config.yaml (shellcheck-py,
+  # pre-commit-hooks). prek reads the same config format Dependabot updates.
+  - package-ecosystem: pre-commit
+    directory: "/"
+    multi-ecosystem-group: dev-tooling
+    cooldown:
+      default-days: 30

.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+# Lint and test the repo with the same npm-pinned tools contributors run
+# locally (prek + Prettier + ShellCheck for lint, Bats for tests). Everything is
+# installed by `npm ci` from the committed package-lock.json, so CI and local
+# use identical versions.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: npm
+      - name: Cache prek hook environments
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/prek
+          key: prek-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            prek-${{ runner.os }}-
+      - run: npm ci
+      - run: npm run lint
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: npm
+      - run: npm ci
+      - run: npm test

.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+# Pre-commit hooks for the han plugin suite, run with prek.
+#
+# Run every hook manually with `npm run lint` (prek run --all-files).
+
+# Files no hook ever touches: static archives and vendored assets.
+exclude: "^(docs/plans/|docs/research/|han-reporting/skills/html-summary/assets/)"
+
+repos:
+  # Prettier owns formatting for Markdown, JSON, YAML, and JS: 120-column prose,
+  # ordered-list numbering, and unwrapped .github templates (.prettierrc.json),
+  # with ignore rules in .prettierignore. Running the local devDependency keeps
+  # Prettier's version in package.json only, not duplicated in a hook mirror.
+  # It runs first so the hygiene fixers below never fight it.
+  - repo: local
+    hooks:
+      - id: prettier
+        name: prettier
+        entry: npx prettier --write --ignore-unknown
+        language: system
+        types_or: [markdown, json, yaml, javascript]
+
+  # Lint shell scripts. prek builds the environment; no Docker, no global install.
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+
+  # Hygiene checks. The whitespace/EOL fixers exclude the file types Prettier
+  # already normalizes (Markdown, JSON, YAML, JS), so Prettier owns those and
+  # these cover the rest (shell scripts, dotfiles, LICENSE) with no overlap.
+  # check-yaml and check-json are intentionally omitted: Prettier parses and so
+  # validates those types already.
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: '\.(md|markdown|json|ya?ml|jsx?|mjs|cjs)$'
+      - id: end-of-file-fixer
+        exclude: '\.(md|markdown|json|ya?ml|jsx?|mjs|cjs)$'
+      - id: fix-byte-order-marker
+        exclude: '\.(md|markdown|json|ya?ml|jsx?|mjs|cjs)$'
+      - id: mixed-line-ending
+        args: [--fix=lf]
+        exclude: '\.(md|markdown|json|ya?ml|jsx?|mjs|cjs)$'
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-shebang-scripts-are-executable
+      - id: check-executables-have-shebangs
+      - id: check-symlinks
+      - id: destroyed-symlinks
+      - id: check-vcs-permalinks

.prettierignore

@@ -0,0 +1,10 @@
+# Static historical artifacts: left as written.
+docs/plans/
+docs/research/
+
+# Vendored third-party assets: checked in verbatim, never reformat.
+han-reporting/skills/html-summary/assets/
+
+# Dependencies and generated files.
+node_modules/
+package-lock.json

.prettierrc.json

@@ -0,0 +1,12 @@
+{
+  "printWidth": 120,
+  "proseWrap": "always",
+  "overrides": [
+    {
+      "files": ".github/**/*.md",
+      "options": {
+        "proseWrap": "never"
+      }
+    }
+  ]
+}

CONTRIBUTING.md

@@ -11,6 +11,7 @@ This page is for contributors: anyone adding, editing, or restructuring skills,
 - **Every skill and every agent gets a long-form doc.** No exceptions. See the [coverage rule](./docs/templates/coverage-rule.md).
 - Use the [long-form skill template](./docs/templates/skill-long-form-template.md) or the [agent template](./docs/templates/agent-long-form-template.md).
 - The root [CLAUDE.md](./CLAUDE.md) carries the at-a-glance project map for assistants and contributors.
+- Before your first commit, run `npm install`. It installs the pinned dev tools and wires up the git hook. See [Setting up your environment](#setting-up-your-environment).
 
 ## Before you start
 
@@ -21,6 +22,32 @@ Read these once:
 - **[`han-plugin-builder/skills/guidance/references/agent-building-guidelines/`](./han-plugin-builder/skills/guidance/references/agent-building-guidelines/).** The agent-authoring rules: external files, model selection, domain focus, graceful degradation, multi-agent economics.
 - **[Root `CLAUDE.md`](./CLAUDE.md).** Repo conventions, doc map, and where each kind of file lives.
 
+## Setting up your environment
+
+Han's dev tooling is managed as npm devDependencies, so a single `npm install` sets everything up at pinned versions with nothing installed globally. It installs [prek](https://github.com/j178/prek) (the git-hook runner), [Prettier](https://prettier.io) (formatting), and [Bats](https://github.com/bats-core/bats-core) (shell tests).
+
+One-time setup, from the repo root:
+
+1. Install [Node.js](https://nodejs.org/) (the current LTS is fine).
+2. Run `npm install`. It installs the pinned tools into `node_modules/`. Nothing lands on your global PATH, so tool versions never clash with your other projects.
+3. If you want pre-commit hooks, run `npx prek install`.
+
+Everyday use:
+
+- `npm run lint` runs every hook over the whole repo (`prek run --all-files`).
+- `npm test` runs the shell tests (`bats --recursive test/`).
+- If installed, every commit runs the lint hooks (Prettier, ShellCheck, and file hygiene) on your staged files.
+
+CI runs the same lint hooks and the tests on every pull request.
+
+How Prettier treats your files:
+
+- It formats Markdown, JSON, YAML, and JavaScript. Prose reflows to 120 columns and ordered lists keep their `1.`, `2.`, `3.` numbering (configured in `.prettierrc.json`).
+- PR and issue templates under `.github/` are unwrapped rather than wrapped, because GitHub renders every newline in a PR or issue body as a line break.
+- The static archives under `docs/plans/` and `docs/research/`, and the vendored assets under `han-reporting/skills/html-summary/assets/`, are left untouched (`.prettierignore`).
+
+Shell scripts are linted with ShellCheck. Tests live in `test/` as `*.bats` files and run in CI rather than on commit; run them locally with `npm test`.
+
 ## Which plugin does the change belong in?
 
 Han ships as a family of plugins. Most carry components; the `han` meta-plugin bundles the others. Decide where your change goes before you scaffold anything. (For the user-facing version of this map, see [Choosing a Han plugin](./docs/choosing-a-han-plugin.md).)
@@ -112,6 +139,8 @@ Before opening the PR, run through this checklist:
 - [ ] Internal links resolve.
 - [ ] No em-dashes anywhere in the doc.
 - [ ] No *"actually," "just," "leverage," "utilize," "showcase," "robust" (vague), "It's worth noting," "Importantly,"* or other voice violations.
+- [ ] `npm run lint` passes.
+- [ ] `npm run test` passes.
 
 ## Related Documentation