codehere 1.0.2 → 2.0.0-beta.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024
+Copyright (c) 2026 Muhammad Ega
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -1,67 +1,110 @@
-# codehere
+# Codehere
+
+**A team brain for vibe coders.** It stops your AI coding agent from going in circles, checks "done" for real, and shares what your team learns. It works through plain files in git.
+
+Codehere is built to remove work, not add it. You keep using Claude Code as usual. Codehere talks to the agent, not to you, and stays silent unless it helps.
+
+## What it does
+
+| Without Codehere, you… | With Codehere |
+|---|---|
+| Re-explain your team's rules every session | Team rules load into every session automatically |
+| Type "still broken" and the agent guesses what you mean | Codehere adds the last error, the failing test and the files changed to your short message |
+| Ask for a whole app with no way to check it | The agent asks you one question first: "How will you know it works?" Your answer becomes a test |
+| Watch the agent try the same failing fix again and again | After the same error 3 times, the agent is told to stop and find the root cause first |
+| Trust "Done!" and find it broken later | Codehere runs your tests itself. If they fail, the agent goes back to work. |
+| Miss that a test was skipped or deleted to make it "pass" | The agent is blocked and asked to restore it |
+| Lose a long, messy session and start over from scratch | When a long session keeps hitting the same error, the agent suggests `codehere brief`: one clean spec that the next session loads |
+| Write a long message to ask a friend for help | `codehere help` writes a redacted help card for you |
+| Solve a bug that a teammate already solved last week | Their fix reaches your agent the first time the error appears |
+
+## Install (2 minutes)
+
+```bash
+npm install -g codehere@next   # the 2.0 beta; codehere@latest is still 1.x
+cd your-project
+codehere init               # finds your test command, adds hooks to .claude/settings.json
+git add .codehere .claude/settings.json .gitignore
+git commit -m "Add Codehere" && git push
+```
 
-> **Re-runs the tests an AI says passed, and tells you whether they did.**
-> `codehere check` on your machine, or the GitHub Action on every pull request. No account.
+Each teammate installs the CLI once (`npm install -g codehere@next`). The hooks and the brain arrive through git.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](https://github.com/muhammadegaa/codehere/blob/main/LICENSE)
+## The team loop
 
-`codehere check` re-runs your project's tests itself and reports the real result, so you do not have to take an agent's "all tests pass" on trust. It detects `npm test`, `node --test`, `pytest`, `go test`, `cargo test` and vitest or jest configs.
+```bash
+codehere rule "Prices are in cents. Never use floats for money."   # every agent follows it
 
-## Install
+# stuck?
+codehere help "Cart total ignores quantity"   # writes .codehere/help/<id>.md (redacted)
+git add .codehere && git commit -m "help: cart" && git push
 
-```
-npx codehere check
+# teammate, after git pull (their agent also mentions it at session start)
+codehere inbox
+codehere reply <id> "Use price * qty; same bug was in checkout.js" --solved
+git add .codehere && git commit -m "answer" && git push
 ```
 
-The npm release is 1.0.1, which has `check` with `--json` and `--proof`. The options `--base` and `--claim` below are in this repository (version 1.0.2) and are not published yet. To use them now, build from source: `cd agent && npm ci && npm run build && node dist/index.js check`.
+`--solved` turns the answer into a **team lesson**. From then on, any teammate's agent that hits a similar error gets that fix automatically. When an agent solves a repeated error by itself, Codehere asks it to write a short lesson too.
 
-## The four commands
+Don't want to commit help cards? Copy the printed text into WhatsApp, Discord or Slack instead.
+
+## Commands
 
 ```
-codehere check                                    # re-run the tests here
-codehere check --base origin/main                 # also read everything this branch changed
-codehere check --claim "<the agent's summary>"    # flag test files it named that do not exist
-codehere check --proof                            # a receipt you can paste into a pull request
+codehere init [--test "npm test"]       set up (safe to run again)
+codehere rule ["text"]                  add or list team rules
+codehere lesson ["problem" --fix "..."] add or list lessons
+codehere brief [--gemma]                restart brief for a fresh session
+codehere help ["question"] [--gemma]    help card for a teammate
+codehere inbox [--all]                  teammates' help cards
+codehere show <id>                      read a help card
+codehere reply <id> "answer" [--solved] answer; --solved makes a lesson
+codehere status                         what Codehere has seen
+codehere stats                          turns to green, loops stopped, context size
 ```
 
-`codehere help check` lists the options. `--json` adds a `verdict` (`pass`, `fail`, `unverified` or `skipped`) and the receipt text.
-
-Exit codes:
-
-- **0**: the tests ran and passed, no test was weakened, no named test file is missing, and the weakened-test scan finished.
-- **1**: the tests failed; the runner reported no test that ran (0 tests, or every test skipped); the change made a test check nothing (an assertion swapped for `assert True` or `assert.ok(true)`, a skip marker, an assertion commented out, or a `return` above it); or a test file named in `--claim` is not in the repository. Usage errors (an unknown `--base`, a missing folder, an unknown option) also exit 1, with the message on stderr and nothing on stdout, and so does an internal error. Pass the claim as `--claim=<text>`: in `--claim --json` the claim is the text `--json`.
-- **2**: nothing could be verified: the run timed out, no test command was recognized, the runner is not installed, the re-run was turned off, or the weakened-test scan could not run (git is not installed, git could not read the repository, or the diff could not be read).
-
-Settings, as environment variables: `CODEHERE_TEST_CMD` replaces the detected test command (split on whitespace, no shell); `CODEHERE_RERUN_TIMEOUT_MS` sets the time limit in whole milliseconds (default 120000, two minutes, also used for a value that is not a whole number from 1 to 2147483647); `CODEHERE_RERUN_TESTS=0` turns the re-run off. Detection covers `npm test` (a `test` script in `package.json`), `go test ./...`, `cargo test`, `pytest` (with `pytest.ini`, `conftest.py` or a pytest section in `pyproject.toml` or `setup.cfg`), `vitest.config.ts`/`.js`, `jest.config.js`/`.ts`, and `node --test` for `*.test.js` files.
-
-"No test ran" is read from the runner's own summary for node:test, pytest, jest, vitest and Go's `[no test files]`. A Go package with test files but no tests (`[no tests to run]`), `cargo test` with 0 tests, jest with `--passWithNoTests`, mocha, and a test script that only prints "No tests found" read as a pass. A test script that leaves a background process holding its output open is reported as timed out, even when the tests passed.
+## What lives where
 
-## GitHub Action
-
-A GitHub Action that posts the receipt on each pull request is in [`action/`](https://github.com/muhammadegaa/codehere/tree/main/action). It runs `npx codehere@<version> check --json --base origin/<base> --claim=<PR body>`. Its default version is 1.0.2, which is not on npm yet, so until 1.0.2 is published the Action reports `unverified` and the job stays green with a warning. The 120-second default time limit applies, and the Action has no input to change it. With the default `fail-on-unverified: false`, a pull request that makes the suite unrunnable (removes the test script, breaks the runner) gets `unverified` and a green job with a warning, and a `skipped` verdict (the re-run turned off in the workflow) gets a green job with no warning. Set `fail-on-unverified: true` to fail the job on `unverified`. It is not published to the marketplace.
-
-## What it does not catch
+```
+.codehere/
+  rules.md        team rules (written by people)
+  lessons/        solved errors, one markdown file each
+  help/           help cards
+  briefs/         restart briefs
+  config.json     test command, loop threshold
+  local/          this machine only, git-ignored
+```
 
-- **Weakened tests.** The detector reads Python (`test_*.py`, `*_test.py`), JavaScript and TypeScript (`*.test.*`, `*.spec.*`), Go (`*_test.go`) and PHP (`*Test.php`) test files, and files under `test`, `tests` or `__tests__`. It flags an assertion replaced by an always-true one (`assert True`, `assert.ok(true)`, `assertTrue(True)`, a value compared with itself), a skip marker (including `skipif(True)`, `it.only(`, `test.only(` or `describe.only(` outside strings and `//` comments (including `test.describe.only(`), and in JavaScript, TypeScript and Vue files `fit(` or `fdescribe(` at the start of a statement, after `=>`, or after `await`, `return` or `void`; variants such as `test.only.each` are not flagged, a JavaScript helper or method named `fit` at the start of a statement is flagged, and `.vue` files are read only under `test`, `tests` or `__tests__`), a commented-out assertion and an early `return`. It does not flag a deleted assertion, a deleted test or test file, a loosened expectation, an always-true check written another way, or an edited test script. A very small test file that is renamed and changed in the same commit can read to git as a new file, and a new file is not scanned. Without `--base` it sees only uncommitted changes, so a weakened test that is already committed passes; with `--base <ref>` it sees everything since the branch left that ref. Only test files are diffed; if their diff cannot be read (over 64 MB), the run is reported as unverified. In a folder with no git repository and no `--base`, or before the first commit, the scan is skipped and the output says so. When git is missing or fails on a repository that is there, or `--base` is given outside a repository, the run is reported as unverified.
-- **`--claim`** finds test files named in the summary in plain text, in quotes or backticks, in markdown bold or italics, in brackets, in `path::test` form and with a `:line` suffix. It ignores absolute paths, Windows backslash paths and Java `*Test.java` names. A file counts as present when any file with the same name exists in the checkout (outside `node_modules`, `dist`, `build`, `vendor`, `target` and virtual environments), so a file in the wrong folder is not reported. The search goes 8 folders deep and stops after 50,000 entries, so a named file deeper than that, or in a larger checkout, is reported as missing.
-- **A passing suite with a broken build, and code the tests do not cover.** A receipt says what the test suite showed, not that the software is correct.
-- **Who controls the tests.** `check` runs the project's own test command, so whoever controls that command controls the result, and whoever controls the environment can point the weakened-test scan at another tree (`GIT_DIR`, `GIT_WORK_TREE`). For a pull request from someone you do not trust, a receipt is not evidence. In the Action, use the `pull_request` trigger, not `pull_request_target`.
+Everything is plain markdown, so you can read, edit, review and delete it like any other file.
 
-## What has been measured
+## Design rules (from the research)
 
-- **False-done eval, 22 cases.** 14 false "tests pass" or "all green" claims (6 reconstructed from public posts, 8 planted) and 8 true ones. `codehere check` caught 12 of the 14 false claims, missed 2 (a green suite with a broken build, and green tests with a broken production job), and raised 0 false alarms on the 8 true ones. Result: [`agent/eval/false-done-result.json`](https://github.com/muhammadegaa/codehere/blob/main/agent/eval/false-done-result.json), produced by `node eval/false-done.mjs`. The cases were written to fit the detectors, so this is a small set and not a general rate.
-- **How often agent pull requests carry a failing claim: not measured.** A pre-registered study (S11) had two models label 299 public agent pull requests. They disagreed (Cohen's kappa 0.092), so the study reports no rate. The report, with the method and its limits: [`agent/eval/promise-verification/studies/S11-demand/REPORT.md`](https://github.com/muhammadegaa/codehere/blob/main/agent/eval/promise-verification/studies/S11-demand/REPORT.md).
+- **No AI in the decision path.** Loops, failed tests and tampering are detected with plain rules, so Codehere doesn't inherit the agent's mistakes.
+- **It talks to the agent, not to you.** If Codehere is wrong, the agent does one extra check. You lose nothing.
+- **Silent on normal turns.** Your prompt gets extra context only after a failure, for a feature with no way to check it, or in a long session stuck on one error. Each at most once, under 300 tokens.
+- **It only reacts to this session's work.** Changes you had before the session are ignored. If the agent changed nothing, Codehere does nothing.
+- **It never traps the agent.** At most 3 "not done yet" messages per session, then it lets go.
+- **It fails open.** If anything breaks, the hook exits quietly and the agent carries on.
+- **Small model, small job.** Gemma 4 (via Ollama) is optional and only writes summaries for briefs and help cards, which you read before using. Turn it on with `--gemma`.
+- **Only human-confirmed context at session start.** Rules are written by people. Lessons appear only when a matching error shows up, because auto-generated context files can make agents worse.
 
-## Development
+## Try the demo (no Claude account needed)
 
+```bash
+node demo/demo.mjs          # two teammates, one repo, the whole loop
+node demo/demo.mjs --step   # press Enter between scenes (good for a live talk)
+npm test                    # end-to-end checks
 ```
-cd agent
-npm ci
-npm test            # build, then vitest
-npm run lint
-node eval/false-done.mjs
-```
 
-## License
+## Known limits (2.0.0, not released yet)
+
+- Claude Code only for now. Gemini CLI and Codex hooks are next.
+- Lessons match by error text. Very generic errors can bring up a lesson that doesn't fit, which is why the agent is told it "may apply".
+- Redaction catches common keys, tokens and emails. Always read a help card before sharing it.
+- The "done" check needs a test command. Without one, only the tampering check runs.
+- Sharing is through git. There is no server, so teammates see updates after `git pull`.
+- Prompt checks are plain word lists (English and Indonesian). They can miss a short prompt in another language.
+- The weakened-test scan catches skipped tests, deleted test files and removed assertions. It does not yet catch an edited expected value; see `docs/overlap-with-check.md`.
 
-MIT. See [`LICENSE`](https://github.com/muhammadegaa/codehere/blob/main/LICENSE).
+MIT licensed.

package/bin/codehere.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { runHook } from '../src/hooks.js';
+import * as cmd from '../src/commands.js';
+
+const argv = process.argv.slice(2);
+const BOOLEAN = new Set(['gemma', 'solved', 'all', 'help', 'h']);
+const flags = {};
+const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith('--')) {
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (!BOOLEAN.has(key) && next !== undefined && !next.startsWith('--')) {
+      flags[key] = next;
+      i++;
+    } else flags[key] = true;
+  } else pos.push(a);
+}
+
+const [command, ...rest] = pos;
+
+const USAGE = `codehere · a git-native team brain for vibe coders
+
+Setup
+  codehere init [--test "npm test"]   set up .codehere/ and Claude Code hooks
+
+Team brain
+  codehere rule ["text"]              add a team rule (or list rules)
+  codehere lesson ["problem" --fix "what fixed it" --sig "error text"]
+                                      add a lesson (or list lessons)
+
+When you're stuck
+  codehere brief [--gemma]            write a restart brief; the next session loads it
+  codehere help ["question"] [--gemma]
+                                      write a redacted help card for a teammate
+  codehere inbox [--all]              see teammates' help cards
+  codehere show <id>                  read a help card
+  codehere reply <id> "answer" [--solved]
+                                      answer; --solved turns it into a team lesson
+
+  codehere status                     what Codehere has seen
+  codehere stats                      turns to green, loops stopped, session size
+
+Hooks (called by Claude Code, not by you)
+  codehere hook session-start | prompt | post-tool | stop
+`;
+
+const run = async () => {
+  switch (command) {
+    case 'hook':
+      return runHook(rest[0]);
+    case 'init':
+      return cmd.init(flags);
+    case 'rule':
+    case 'rules':
+      return cmd.rule(rest.join(' '));
+    case 'lesson':
+    case 'lessons':
+      return cmd.lesson(rest.join(' '), flags);
+    case 'brief':
+      return cmd.brief(flags);
+    case 'help':
+      if (flags.h) return console.log(USAGE);
+      return cmd.help(rest.join(' '), flags);
+    case 'inbox':
+      return cmd.inbox(flags);
+    case 'show':
+      return cmd.show(rest[0]);
+    case 'reply':
+      return cmd.reply(rest[0], rest.slice(1).join(' '), flags);
+    case 'status':
+      return cmd.status();
+    case 'stats':
+      return cmd.stats();
+    default:
+      if (!command || command === '-h') return console.log(USAGE);
+      // stderr only: a hook's stdout can land in the agent's context (e.g. a codehere 1.x
+      // user-level hook such as `codehere scan-tool`). Exit 0 when a hook called us.
+      console.error(`Unknown command "${command}". Run codehere --help.`);
+      if (process.stdin.isTTY) process.exitCode = 1;
+  }
+};
+
+run().catch((err) => {
+  // hooks must never break the agent
+  if (command === 'hook') process.exit(0);
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,79 +1,35 @@
 {
   "name": "codehere",
-  "version": "1.0.2",
-  "description": "Re-runs the tests an AI says passed, and tells you whether they did. Flags weakened tests and test files that do not exist.",
-  "main": "dist/index.js",
+  "version": "2.0.0-beta.0",
+  "description": "A git-native team brain for vibe coders. Silent fixes for AI coding agents: breaks doom loops, verifies 'done', blocks test tampering, and shares what your team learned.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muhammadegaa/codehere.git",
+    "directory": "v2"
+  },
+  "homepage": "https://github.com/muhammadegaa/codehere/tree/v2-team-brain/v2#readme",
   "type": "module",
   "bin": {
-    "codehere": "dist/index.js",
-    "ch": "dist/index.js"
+    "codehere": "bin/codehere.js"
   },
   "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
+    "bin",
+    "src",
+    "README.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=18"
   },
-  "os": [
-    "darwin",
-    "linux"
-  ],
   "scripts": {
-    "prepare": "bash ../scripts/install-hooks.sh || true",
-    "prebuild": "rm -rf dist",
-    "build": "tsc",
-    "postbuild": "chmod +x dist/index.js",
-    "prepublishOnly": "npm run build && find dist -name '*.map' -delete && find dist -name '*.d.ts' -delete && find dist -name '*.d.ts.map' -delete",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "test": "npm run build && vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint src/ --ext .ts",
-    "knip": "knip",
-    "knip:gate": "node scripts/knip-gate.mjs",
-    "arch:gate": "tsc --noEmit && eslint src/ --ext .ts && node scripts/knip-gate.mjs",
-    "format": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts' 'test/**/*.ts'",
-    "sbom": "npm sbom --sbom-format=spdx --omit=dev",
-    "pretag:check": "../scripts/pretag-npm-check.sh"
+    "test": "node test/e2e.mjs"
   },
   "keywords": [
-    "ai-coding-agents",
-    "test-verification",
-    "ci",
-    "github-action",
     "claude-code",
-    "codex",
-    "cli-tool",
-    "typescript"
+    "ai-agents",
+    "vibe-coding",
+    "hooks",
+    "team",
+    "memory"
   ],
-  "author": "The codehere authors",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/muhammadegaa/codehere.git"
-  },
-  "bugs": {
-    "url": "https://github.com/muhammadegaa/codehere/issues"
-  },
-  "homepage": "https://github.com/muhammadegaa/codehere",
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^11.1.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^20.19.25",
-    "eslint": "^10.2.0",
-    "eslint-import-resolver-typescript": "^4.4.5",
-    "eslint-plugin-import-x": "^4.16.2",
-    "knip": "^6.16.1",
-    "prettier": "^3.8.3",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.58.2",
-    "vitest": "^4.1.4"
-  }
+  "license": "MIT"
 }

package/src/brain.js

@@ -0,0 +1,186 @@
+// The team brain: plain markdown files in .codehere/, committed to git.
+// Local, per-machine state lives in .codehere/local/ (git-ignored).
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+export function findRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.codehere'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function paths(root) {
+  const base = path.join(root, '.codehere');
+  return {
+    base,
+    config: path.join(base, 'config.json'),
+    rules: path.join(base, 'rules.md'),
+    lessons: path.join(base, 'lessons'),
+    help: path.join(base, 'help'),
+    briefs: path.join(base, 'briefs'),
+    local: path.join(base, 'local'),
+    state: path.join(base, 'local', 'state.json'),
+  };
+}
+
+export function ensureDirs(root) {
+  const p = paths(root);
+  for (const d of [p.base, p.lessons, p.help, p.briefs, p.local]) {
+    fs.mkdirSync(d, { recursive: true });
+  }
+  return p;
+}
+
+const DEFAULT_CONFIG = {
+  testCommand: null,
+  verifyOnStop: true,
+  loopThreshold: 3,
+  testTimeoutSeconds: 120,
+  longSessionTokens: 120000,
+  gemmaModel: 'gemma4:e4b',
+};
+
+export function readConfig(root) {
+  const p = paths(root);
+  try {
+    return { ...DEFAULT_CONFIG, ...JSON.parse(fs.readFileSync(p.config, 'utf8')) };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function writeConfig(root, cfg) {
+  fs.writeFileSync(paths(root).config, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+// ---------- local session state ----------
+
+export function readState(root) {
+  try {
+    return JSON.parse(fs.readFileSync(paths(root).state, 'utf8'));
+  } catch {
+    return { sessions: {}, lastSession: null, lastGreen: null, pendingBrief: null };
+  }
+}
+
+export function writeState(root, state) {
+  const p = paths(root);
+  fs.mkdirSync(p.local, { recursive: true });
+  fs.writeFileSync(p.state, JSON.stringify(state, null, 2));
+}
+
+export function session(state, id) {
+  const key = id || 'default';
+  if (!state.sessions[key]) {
+    state.sessions[key] = {
+      errors: {},
+      rawErrors: {},
+      shownLessons: [],
+      stopBlocks: 0,
+      lessonAsked: false,
+      startedAt: new Date().toISOString(),
+      transcript: null,
+    };
+  }
+  state.lastSession = key;
+  state.sessions[key].lastActive = new Date().toISOString();
+  // keep the state file small: drop sessions older than the 20 most recent
+  const keys = Object.keys(state.sessions);
+  if (keys.length > 20) {
+    keys
+      .sort((a, b) => (state.sessions[a].startedAt || '').localeCompare(state.sessions[b].startedAt || ''))
+      .slice(0, keys.length - 20)
+      .forEach((k) => delete state.sessions[k]);
+  }
+  return state.sessions[key];
+}
+
+// ---------- markdown with simple frontmatter ----------
+
+export function parseDoc(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { meta: {}, body: text };
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const i = line.indexOf(':');
+    if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return { meta, body: m[2] };
+}
+
+export function renderDoc(meta, body) {
+  const head = Object.entries(meta)
+    .map(([k, v]) => `${k}: ${String(v).replace(/\n/g, ' ')}`)
+    .join('\n');
+  return `---\n${head}\n---\n${body.trimEnd()}\n`;
+}
+
+export function listDocs(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+    .map((f) => {
+      const file = path.join(dir, f);
+      const { meta, body } = parseDoc(fs.readFileSync(file, 'utf8'));
+      return { id: f.replace(/\.md$/, ''), file, meta, body };
+    });
+}
+
+export function slug(text, max = 40) {
+  return (
+    String(text)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, max) || 'note'
+  );
+}
+
+export function stamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+export function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+// ---------- rules ----------
+
+export function readRules(root) {
+  const file = paths(root).rules;
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, 'utf8')
+    .split('\n')
+    .filter((l) => l.startsWith('- '))
+    .map((l) => l.slice(2).trim());
+}
+
+// ---------- git helpers (all fail-safe) ----------
+
+export function git(root, args) {
+  try {
+    return execSync(`git ${args}`, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch {
+    return '';
+  }
+}
+
+export function isGitRepo(root) {
+  return git(root, 'rev-parse --is-inside-work-tree') === 'true';
+}
+
+export function me(root) {
+  return git(root, 'config user.name') || process.env.USER || 'someone';
+}