an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
chore(contributing): before/after evidence is mandatory, and enforced
Chaitanya Giri6e40337a522e
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlindex d04bd000..0f5e65d9 100644--- a/.github/ISSUE_TEMPLATE/bug_report.yml+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -4,35 +4,71 @@ labels: ["bug"]body:- type: markdownattributes:- value: Thanks for taking the time to file a bug! Please fill out the sections below.+ value: |+ **A screenshot or recording is required.** We get more reports than we can+ reproduce blind, and the ones with a picture get fixed first because they+ are the ones we can actually see. If you can only give us one thing, give+ us the recording.- type: textareaid: what-happenedattributes:label: What happened?- description: A clear description of the bug, plus what you expected instead.+ description: What you saw, and what you expected instead.validations:required: true- type: textareaid: reproattributes:label: Steps to reproduce+ description: Numbered steps, starting from a fresh launch. If we can't follow them, we can't fix it.placeholder: |- 1. Run `npm run dev`+ 1. Launch the app2. Add an agent with command `...`3. See errorvalidations:required: true+ - type: textarea+ id: evidence+ attributes:+ label: Screenshot or screen recording+ description: |+ **Required.** Drag the file straight into this box and GitHub will upload it.+ A recording beats a still for anything that moves, hangs, or flickers.+ If the bug is invisible on screen, show us the terminal or the log instead —+ but show us something.+ placeholder: Drag an image or video here.+ validations:+ required: true- type: textareaid: logsattributes:- label: Logs / screenshots- description: Console output, stack traces, or a screenshot/clip if it's visual.+ label: Logs / stack trace+ description: Console output or a stack trace, if you have one. Paste as text, not a screenshot of text.render: shell+ - type: dropdown+ id: os+ attributes:+ label: Operating system+ options:+ - macOS (Apple Silicon)+ - macOS (Intel)+ - Windows+ - Linux+ validations:+ required: true- type: input- id: macos+ id: os-versionattributes:- label: macOS version- placeholder: e.g. 15.0+ label: OS version+ placeholder: e.g. macOS 15.0, Windows 11 23H2, Ubuntu 24.04+ validations:+ required: true+ - type: input+ id: app-version+ attributes:+ label: Munder Difflin version+ description: Settings → the version is on the hero card. Or `Munder Difflin → About`.+ placeholder: e.g. 0.4.5validations:required: true- type: input@@ -43,16 +79,20 @@ body:validations:required: true- type: input- id: claude+ id: agent-cliattributes:- label: Claude Code version (if relevant)- placeholder: claude --version+ label: Agent CLI and version (if relevant)+ placeholder: e.g. claude --version, codex --version- type: checkboxesid: checksattributes:label: Pre-flightoptions:- - label: I re-ran `npm install` so `node-pty` is rebuilt for the current Electron ABI.+ - label: I attached a screenshot or recording above.+ required: true+ - label: I'm on the latest release, or I've said above why I can't be.+ required: true+ - label: I re-ran `npm install` so `node-pty` is rebuilt for the current Electron ABI (source installs only).required: true- label: I searched existing issues and this isn't a duplicate.required: truediff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlindex ba63b527..c9fb1879 100644--- a/.github/ISSUE_TEMPLATE/feature_request.yml+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -2,24 +2,45 @@ name: Feature requestdescription: Suggest an idea or improvement.labels: ["enhancement"]body:+ - type: markdown+ attributes:+ value: |+ **A picture is required here too.** Not a mockup of your idea necessarily —+ a shot of the screen as it is today, with the gap in it. It is the fastest+ way to make a proposal concrete, and it stops good ideas dying as prose.+ Ideas still forming are better in+ [Discussions](https://github.com/chaitanyagiri/munder-difflin/discussions).- type: textareaid: problemattributes:label: Problem / motivation- description: What are you trying to do, and what's getting in the way?+ description: What are you trying to do, and what's getting in the way? Describe the situation you hit, not the feature you want.validations:required: true- type: textareaid: proposalattributes:label: Proposed solution- description: What would you like to see happen?+ description: What should happen instead?+ validations:+ required: true+ - type: textarea+ id: evidence+ attributes:+ label: Screenshot, mockup or recording+ description: |+ **Required.** Drag the file straight into this box.+ Any of these work: the screen today with the gap circled, a sketch of what+ you mean, a recording of the workaround you're doing instead, or the same+ thing done well in another app.+ placeholder: Drag an image or video here.validations:required: true- type: textareaid: alternativesattributes:label: Alternatives considered+ description: What you tried, or why the obvious approach doesn't work.- type: dropdownid: areaattributes:@@ -30,7 +51,17 @@ body:- The hive (memory, routing, GOD agent)- Files / git- Onboarding / config+ - Updates / releases- Design system- Othervalidations:required: true+ - type: checkboxes+ id: checks+ attributes:+ label: Pre-flight+ options:+ - label: I attached a screenshot, mockup or recording above.+ required: true+ - label: I searched existing issues and discussions, and this isn't a duplicate.+ required: truediff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 4494d949..cd04d907 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -1,8 +1,15 @@-<!-- Thanks for contributing to Munder Difflin! -->+<!-- Thanks for contributing to Munder Difflin.++ Read this line before you go further: a PR without a BEFORE and an AFTER+ is not reviewable and will not be merged. The `PR evidence` check runs the+ moment you open this and will tell you if it is missing. Keep the `Before`+ and `After` headings below exactly as they are — the check reads them. -->## What & why-<!-- What does this change do, and why? Link any related issue: Closes #123 -->+<!-- What changed, and why it needed to. Two or three sentences beats a+ bullet list of file names — we can read the diff, we cannot read your+ reasoning. If this fixes an issue, link it: Closes #123 -->## Type of change@@ -12,21 +19,52 @@- [ ] Docs- [ ] Build / CI-## Screenshots / clips+## Evidence++<!-- REQUIRED. Drag images or a screen recording directly under each heading —+ GitHub uploads them inline. Both headings must have something under them.++ No visible UI? You still owe evidence. Record the failing behaviour and+ then the same steps passing: a terminal capture, a log diff, a test that+ goes from red to green. "It has no UI" is not an exemption.++ Truly nothing observable, like a CI tweak or a typo? Say so in+ "What & why" and ask a maintainer for the `no-visual-change` label. -->++### Before++<!-- The problem, as it exists on main right now. -->++### After++<!-- The same view or the same steps, with your change applied.+ Same window size, same theme, same data — a reviewer should be able to+ flip between the two and see only what you changed. -->++## How I tested it++<!-- The actual steps you ran, on which OS. Not "tested locally". -->-<!-- REQUIRED for any visual change: a screenshot or short clip (before/after). -->+- OS:+- Steps:## Discord (optional)-<!-- If you'd like the `employee of the month` role in our Discord when this merges,- put your handle below. Join first so we can find you: https://discord.gg/SEDzP5ZPk5 -->+<!-- For the `employee of the month` role in our Discord when this merges.+ Join first so we can find you: https://discord.gg/SEDzP5ZPk5 -->-Discord:+Discord:## Checklist-- [ ] `npm run typecheck` passes (the de-facto CI gate).+- [ ] **Before and after evidence is attached above**, under both headings.+- [ ] `npm run typecheck` passes.+- [ ] `npm run test:focused` passes.- [ ] `npm run build` succeeds.-- [ ] Any new UI derives from `DESIGN.md` / `tokens.ts` — no ad-hoc colors, spacing, or fonts.-- [ ] If I added art, it's my own or compatibly licensed, and listed in `ATTRIBUTION.md`.-- [ ] PR is focused on a single change.+- [ ] This PR is **one change**. Unrelated fixes belong in their own PR.+- [ ] I read the diff myself before opening this, and there is no debug output,+ commented-out code, or unrelated formatting churn in it.+- [ ] Any new UI derives from `DESIGN.md` / `tokens.ts` — no ad-hoc colors,+ spacing, or fonts.+- [ ] If I added art, it's my own or compatibly licensed, and listed in+ `ATTRIBUTION.md`.diff --git a/.github/workflows/pr-evidence.yml b/.github/workflows/pr-evidence.ymlnew file mode 100644index 00000000..6a0582ce--- /dev/null+++ b/.github/workflows/pr-evidence.yml@@ -0,0 +1,157 @@+name: PR evidence++# Every pull request must show its work: a BEFORE and an AFTER, as images or+# video, in the PR description. This check is what makes that a rule rather than+# a request — it turns the PR red and, with branch protection on, blocks merge.+#+# ── What this deliberately does NOT do ─────────────────────────────────────────+# It cannot stop a PR being OPENED. Nothing on GitHub can; the API has no hook+# that runs before creation. The strongest available enforcement is what this+# does instead: fail within seconds of opening, block the merge button, and say+# in a comment exactly what is missing. Re-edit the description and it re-runs.+#+# ── Why pull_request_target ────────────────────────────────────────────────────+# Contributions come from forks, where `pull_request` hands the job a READ-ONLY+# token, so it could never post the comment that tells someone what to fix.+# `pull_request_target` runs with the base repo's token and write permission.+# That is only safe under one condition, which this file obeys absolutely:+#+# NEVER check out, build, or execute the pull request's code here.+#+# This job reads two strings from the API — the PR body and its labels — and+# nothing else. There is no `actions/checkout`, no `npm`, no run of any script+# from the branch. Adding any of those to this file would hand a fork write+# access to the repository. Put build steps in ci.yml, which is `pull_request`.+on:+ pull_request_target:+ types: [opened, edited, reopened, synchronize, labeled, unlabeled]++permissions:+ pull-requests: write++# A contributor fixing their description shouldn't queue behind their own+# earlier runs — keep only the newest check per PR.+concurrency:+ group: pr-evidence-${{ github.event.pull_request.number }}+ cancel-in-progress: true++jobs:+ evidence:+ name: Before / after evidence+ runs-on: ubuntu-latest+ steps:+ - uses: actions/github-script@v7+ with:+ script: |+ const pr = context.payload.pull_request;+ const body = pr.body || '';+ const labels = (pr.labels || []).map(l => l.name.toLowerCase());++ // ── The maintainer escape hatch ──────────────────────────────────+ // Some changes genuinely have nothing to show: a CI tweak, a typo, a+ // dependency bump. A contributor CANNOT grant themselves this —+ // applying a label needs write access — so the rule stays mandatory+ // for the people it is aimed at, and every waiver is on the record.+ const WAIVER = 'no-visual-change';+ if (labels.includes(WAIVER)) {+ core.info(`Waived: the '${WAIVER}' label is applied by a maintainer.`);+ return;+ }++ // ── What counts as evidence ──────────────────────────────────────+ // Anything a reader can actually SEE in the rendered description.+ // A bare link to a file elsewhere does not count: it rots, it may be+ // private, and it makes a reviewer leave the page.+ const EVIDENCE = [+ /!\[[^\]]*\]\([^)]+\)/, // + /<img\b[^>]*\bsrc\s*=/i, // <img src=...>+ /<video\b/i, // <video ...>+ /https:\/\/github\.com\/user-attachments\/assets\/[\w-]+/i, // drag-and-drop (current)+ /https:\/\/user-images\.githubusercontent\.com\/\S+/i, // drag-and-drop (legacy)+ /https:\/\/\S+\.(png|jpe?g|gif|webp|mp4|mov|webm)\b/i // direct media link+ ];+ const hasEvidence = (text) => EVIDENCE.some(re => re.test(text));++ // Comments are the template's own instructions to the author. Left+ // unfilled they are invisible to a reader, so they must be invisible+ // to this check too — otherwise the empty template would pass.+ const visible = body.replace(/<!--[\s\S]*?-->/g, '');++ // ── Before and after, separately ─────────────────────────────────+ // Two assets in one blob is not the same as a before and an after.+ // The template gives each its own heading; this reads the text under+ // each heading up to the next one, so evidence has to sit in the+ // right place to count for it.+ const section = (name) => {+ const re = new RegExp(+ `^#{1,6}\\s*${name}\\b[^\\n]*\\n([\\s\\S]*?)(?=\\n#{1,6}\\s|$)`,+ 'im'+ );+ return (visible.match(re) || [, ''])[1];+ };++ const before = section('before');+ const after = section('after');++ const missing = [];+ if (!hasEvidence(before)) missing.push('**Before** — no image or video under that heading');+ if (!hasEvidence(after)) missing.push('**After** — no image or video under that heading');++ // A PR that kept the headings but put both assets in one place is a+ // near miss, not a fresh offender. Say so, rather than repeating the+ // generic rule at someone who is clearly trying.+ const nearMiss = missing.length === 2 && hasEvidence(visible);++ const MARKER = '<!-- pr-evidence-check -->';+ const comments = await github.rest.issues.listComments({+ owner: context.repo.owner, repo: context.repo.repo,+ issue_number: pr.number, per_page: 100+ });+ const mine = comments.data.find(c =>+ c.user.type === 'Bot' && (c.body || '').includes(MARKER));++ if (missing.length === 0) {+ // Clear the old complaint so a fixed PR doesn't keep wearing it.+ if (mine) {+ await github.rest.issues.updateComment({+ owner: context.repo.owner, repo: context.repo.repo,+ comment_id: mine.id,+ body: `${MARKER}\n✅ **Evidence received.** Before and after are both attached. Thanks — this is what makes a PR reviewable in one pass.`+ });+ }+ core.info('Before and after evidence both present.');+ return;+ }++ const message = [+ MARKER,+ '### 🚫 This PR is missing its before/after evidence',+ '',+ nearMiss+ ? 'You attached something, but not one under **each** heading. Both are required, and they have to sit under their own heading so a reviewer can tell which is which.'+ : 'Every pull request here has to show its work. Screenshots or a short screen recording, **before the change and after it**.',+ '',+ ...missing.map(m => `- ${m}`),+ '',+ '**How to fix it:** edit the description, keep the `### Before` and `### After` headings from the template, and drag an image or video under each. GitHub uploads it inline. This check re-runs the moment you save.',+ '',+ 'A bug fix with no visible surface still needs it: show the failing behaviour, then the same steps passing. A terminal recording is fine.',+ '',+ `_Genuinely nothing to show — a CI tweak, a typo, a dependency bump? A maintainer can apply the \`${WAIVER}\` label. Please don't ask unless it truly has no observable effect._`,+ '',+ '📖 [CONTRIBUTING.md → Evidence is mandatory](https://github.com/chaitanyagiri/munder-difflin/blob/main/CONTRIBUTING.md#evidence-is-mandatory)'+ ].join('\n');++ if (mine) {+ await github.rest.issues.updateComment({+ owner: context.repo.owner, repo: context.repo.repo,+ comment_id: mine.id, body: message+ });+ } else {+ await github.rest.issues.createComment({+ owner: context.repo.owner, repo: context.repo.repo,+ issue_number: pr.number, body: message+ });+ }++ core.setFailed(`Missing evidence: ${missing.length === 2 ? 'before and after' : missing[0].replace(/\*/g, '')}`);diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 4b467c34..e11be8af 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -42,18 +42,78 @@ npm run dev # live-reloading Electron build> re-run `npm install` (which re-triggers `postinstall`) after confirming your> C/C++ toolchain is installed.+## Evidence is mandatory++**Every pull request must show a before and an after.** Screenshots, or a screen+recording when the thing moves. They go in the PR description, under the+`### Before` and `### After` headings the template gives you.++This is enforced. The `PR evidence` check runs the moment you open a PR, and a+PR that fails it does not merge. Fix the description and the check re-runs on+save. It reads each heading separately, so two images dumped under one of them+will not pass — a reviewer has to be able to tell which is which.++**"My change has no UI" is not an exemption.** It changes the evidence, not the+requirement:++| Kind of change | What before/after looks like |+|---|---|+| Visual | The same view, twice. Same window size, same theme, same data. |+| Bug fix | The bug happening, then the same steps not producing it. |+| Terminal / CLI | A recording of the session, or the output pasted as text. |+| Performance | The measurement before and the measurement after, same machine. |+| Crash / hang | The failure, then the same path completing. |+| Test-only | The suite red, then the suite green. |++Make the two shots comparable. Different window sizes, a light shot against a+dark one, or different data means the reviewer is diffing your screenshots+instead of your change.++The only way out is the `no-visual-change` label, which a maintainer applies+for things with genuinely nothing observable: a CI tweak, a typo, a dependency+bump. You cannot add it yourself, and asking for it on a change that does+something visible will cost you more time than the screenshot would have.+## Before you open a PR-1. **Keep the type-checker green:** `npm run typecheck` (runs both the node and- web TS projects). This is the de-facto CI gate.-2. **Run the tests:** `npm run test:focused` (the core suite), or- `node --test test/*.test.cjs` to run everything in `test/`.-3. **Confirm a production build works:** `npm run build`.-4. **Match the aesthetic.** Any new UI **must** derive from the design tokens in+1. **Attach the before and after.** See above. This is the one that gets PRs+ closed unread, so do it first, not last.+2. **Keep the type-checker green:** `npm run typecheck` (runs both the node and+ web TS projects).+3. **Run the tests:** `npm run test:focused`. If you changed behaviour, add a+ test for it — a bug fix with no test is a bug fix that comes back.+4. **Confirm a production build works:** `npm run build`.+5. **Match the aesthetic.** Any new UI **must** derive from the design tokens in[`DESIGN.md`](./DESIGN.md) / `src/renderer/src/design/tokens.ts` — no ad-hoccolors, spacing, or fonts. `tokens.ts` and `tokens.css` are mirrored; if youchange one, change both.-5. **For anything visual, include a screenshot or short clip** in the PR.+6. **Read your own diff.** Every line of it. Debug logging, commented-out code,+ and reformatting of files you didn't otherwise touch all get a PR sent back.++## What gets a PR closed++We are getting more pull requests than we can review carefully, so the bar has+gone up. These are closed rather than negotiated:++- **No before/after evidence**, and no `no-visual-change` label.+- **More than one change in one PR.** A fix plus a refactor plus a rename is+ three PRs. Split it and every one of them merges faster.+- **Wholesale reformatting** of files, or a diff where the real change is buried+ in whitespace and import reordering.+- **A rewrite nobody asked for.** Large architectural changes need an issue or a+ [discussion](https://github.com/chaitanyagiri/munder-difflin/discussions) with+ agreement **before** you write the code. We would rather say no to a paragraph+ than to a week of your work.+- **Generated or unattributed content** — art that isn't yours or compatibly+ licensed, or a description that doesn't match what the diff does.+- **Dependency additions** that aren't justified in the description. A new+ runtime dependency needs a reason a one-file helper wouldn't have solved.+- **No response for 14 days** on review feedback. Reopen whenever you're ready;+ nothing is lost.++None of this is aimed at first-timers. A small, focused, well-evidenced PR from+someone who has never contributed before gets reviewed ahead of a big one from+someone who has.## Project layout@@ -78,9 +138,18 @@ data-flow overview.## Commit & PR conventions-- Branch off `main`; keep PRs focused on one change.-- Write a clear PR description of *what* changed and *why*.+- Branch off `main`. One change per PR — see+ [What gets a PR closed](#what-gets-a-pr-closed).+- Write a clear description of *what* changed and *why*. We can read the diff;+ we cannot read your reasoning.+- Say how you tested it, and on which OS. "Tested locally" tells us nothing.+- Link the issue you're fixing: `Closes #123`.- Don't commit `node_modules/`, `out/`, or built artifacts (already gitignored).+- Don't force-push after a review has started. It throws away the comparison the+ reviewer was working from.+- **Never put credentials, tokens, internal metrics, or customer data in a+ commit message.** A pushed commit message is public and permanent, and no+ later rewrite retracts it once it has been fetched.## A note on assetsdiff --git a/README.md b/README.mdindex cbaa87f7..5980e33a 100644--- a/README.md+++ b/README.md@@ -313,6 +313,13 @@ Contributions are welcome — this is an early prototype with a lot of surface a`npm run typecheck` green, and **derive any new UI from [`DESIGN.md`](./DESIGN.md) tokens**. Goodfirst areas: wiring real hook events, the add-agent flow, the config drawer, and cross-platform work.+> [!IMPORTANT]+> **Every pull request must show a before and an after** — screenshots, or a recording when the+> thing moves — under the `### Before` and `### After` headings in the PR template. This is checked+> automatically and a PR without it does not merge. "My change has no UI" is not an exemption; it+> just changes what the evidence looks like. See+> [Evidence is mandatory](./CONTRIBUTING.md#evidence-is-mandatory).+Questions, bugs, or want to show off your office? Join the Discord: **<https://discord.gg/SEDzP5ZPk5>**. Add your Discord handle to a PR and you'll get the `employee of the month` role when it merges.## Telemetry