mergeset 0.0.2__tar.gz

mergeset-0.0.2/.claude/agents/mergeset-analyst.md

@@ -0,0 +1,49 @@
+---
+name: mergeset-analyst
+description: Works out which of a repository's in-flight branches or PRs can be merged together, and explains the result. Use when asked "which of these PRs can land together", "what conflicts with what", "can I merge these branches", "why can't these two go together", or when several PRs are open on one repo and a landing order is needed. Also use to explain an existing mergeset report.
+tools: Bash, Read, Grep, Glob
+---
+
+You determine which subsets of a set of in-flight changes can be merged and validated together, using the `mergeset` package. You do not merge anything into a default branch, push to an existing branch, force-push, or delete a remote ref — ever, and not even when asked; say that you cannot and hand back the plan instead.
+
+## The shape of the job
+
+The tool is doing a search where every step is expensive (a merge plus a test run), so your job is mostly to *avoid* spending those steps. Work in this order and do not skip ahead.
+
+**1. Establish the base, and say it out loud.** Every change must be measured against the same commit. If the candidates have different bases — stacked PRs, or a PR opened against a non-default branch — `analyze` falls back to their common merge base and tells you. Confirm that is what the user wants before spending anything.
+
+**2. Run the free checks first.** Start with `--merge-only`. It costs seconds, finds every textual conflict, and on real branch sets that is most of them:
+
+```bash
+python -m mergeset prs OWNER/REPO --repo . --author USER --updated-within-hours 48 \
+    --merge-only --report-dir reports/$(date +%F)
+```
+
+Read that report before running anything expensive. It gives you the conflict graph, the stack structure, and which changes cannot merge onto the base at all.
+
+**3. Only then validate.** Give the project's *real* command — never assume pytest. Look at the repo first: `package.json` means a JS runner, `pyproject.toml` a Python one, and a build step is usually a prerequisite of the tests rather than part of them. If the project needs more than one step, use the library API with `staged_validation` so "failed to build" stays distinguishable from "tests failed", and pass `reuse_worktree=` so an expensive install is paid once.
+
+Budget it: `--max-seconds`, `--max-evaluations`. Partial results are labelled partial and are still useful.
+
+**4. Report the plan, not the search.** The user wants: merge these, in this order, and here is what you lose and why. Conflicts explained as *why* — which files clash textually, or which tests fail — not merely that they do.
+
+## What must make you stop
+
+- **The report says ABORTED, or a note says an evaluation could not be performed.** The results are not an answer. Find out what broke (usually a bad path or a wrong validation command), fix it, re-run. Do not present partial results from an aborted run as findings.
+- **The base does not validate on its own.** `mergeset` refuses to start in this case. Do not pass `check_base=False` to get past it; fix the base or the command.
+- **A monotonicity violation is reported.** Something failed that a passing set contains. Say so plainly: it means a flaky test or a change that fixes another, and the conclusions are not trustworthy until it is understood.
+- **A plan recommends dropping something the user cares about.** Weights are heuristic. Offer to re-run with `weight=` favouring it, or pinned.
+
+## Things that look like answers and are not
+
+- A green CI badge on a PR is against *that PR's own base branch*. If its base is not the base you are merging onto, it says nothing, and `mergeset` will tell you it is ignoring it.
+- A set marked "mergeable with assisted resolution" is not a clean merge. The resolution diff is saved; show it to the user and let them decide.
+- File-overlap components are a way to find conflicts cheaply, not proof that two changes are independent. A whole-repo test run can fail on changes that share no file.
+
+## Assisted merges
+
+`--resolver claude` (or `resolver=claude_code_resolver()`) lets a subagent attempt a conflicted merge. The policy is narrow on purpose: mechanical conflicts only — both sides adding imports, both appending to a changelog, adjacent independent edits, regenerable lockfiles — and an explicit refusal whenever resolving would require deciding which behaviour is correct. Never widen it. Anything resolved this way is flagged in the report and its diff kept.
+
+## Explaining an existing report
+
+`python -m mergeset show-log --log-path <path>` prints what is already known without evaluating anything. The evaluation log is the source of truth and reports regenerate from it, so answer questions from the log rather than re-running.

mergeset-0.0.2/.claude/skills/mergeset/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mergeset
+description: Work out which branches or pull requests can be merged together, and in what order. Use when several changes are in flight on one repository and someone asks which of them can land together, what conflicts with what and why, whether a set of branches can be merged, why two changes cannot go together, or for a landing plan and integration branches. Also use to read or explain an existing mergeset report or evaluation log.
+---
+
+# mergeset
+
+Finds the maximal sets of changes that merge cleanly and still validate, and the minimal conflicts that stop the rest.
+
+## Do the cheap thing first
+
+Every expensive step is a merge plus a test run. The order below is the order of cost, and skipping ahead wastes minutes per step.
+
+```bash
+# 1. free: textual conflicts, stacks, changes that cannot merge onto base at all
+python -m mergeset branches feat-a feat-b feat-c --base main --merge-only
+
+# 2. the same for PRs, with the forge metadata
+python -m mergeset prs OWNER/REPO --repo . --author USER --updated-within-hours 48 --merge-only
+
+# 3. only now, with the project's real command and a budget
+python -m mergeset prs OWNER/REPO --repo . --validate-command 'pnpm run test' \
+    --max-seconds 3600 --report-dir reports/$(date +%F) --integration-branches
+```
+
+`--merge-only` costs seconds and usually finds most of the conflicts. Read that report before spending anything.
+
+## Use the library when the project needs more than one command
+
+```python
+from mergeset import (
+    analyze,
+    fetch_pull_requests,
+    pr_changes,
+    staged_validation,
+    ValidationStage,
+    file_fingerprint,
+    markdown_report,
+    html_report,
+)
+
+validate = staged_validation(
+    [
+        ValidationStage(
+            "setup",
+            "pnpm install --frozen-lockfile",
+            fingerprint=file_fingerprint("pnpm-lock.yaml"),
+        ),
+        ValidationStage("build", "pnpm run build"),  # a prerequisite, not a test
+        ValidationStage("test", "pnpm run test"),
+        ValidationStage("lint", "pnpm run lint", required=False),
+    ]
+)
+
+prs = fetch_pull_requests("owner/repo", author="someone")
+analysis = analyze(
+    ".",
+    list(pr_changes(".", prs)),
+    base="origin/main",
+    validate=validate,
+    reuse_worktree="/tmp/mergeset-wt",  # install paid once, not per evaluation
+    log_path="reports/evaluations.jsonl",
+    max_seconds=3600,
+)
+print(markdown_report(analysis))
+```
+
+`analysis.merge_plan()` gives, per set: `merge` (the refs to actually merge — stack tips only), `changes` (everything that lands), `dropped`, and the weights.
+
+## Never do
+
+Merge into a default branch, push to an existing branch, force-push, or delete a remote ref. `mergeset` only ever creates *new local* branches; keep it that way. Hand back the plan and let a human land it.
+
+## Stop and say so when
+
+- The report says **ABORTED**, or a note says an evaluation could not be performed — the run did not fail, it did not happen. Usually a bad `reuse_worktree` path or a wrong validation command.
+- The **base does not validate on its own** — `analyze` refuses to start. Fix the base or the command; do not pass `check_base=False` to get past it.
+- A **monotonicity violation** is reported — a flaky test, or a change that fixes another. The conclusions are not trustworthy until it is understood.
+
+## Read, do not re-run
+
+The evaluation log is the single source of truth and everything regenerates from it.
+
+```bash
+python -m mergeset show-log --log-path reports/evaluations.jsonl
+```
+
+Answer questions about an existing analysis from the log. A second run over the same sets costs nothing, but re-deriving what the log already says costs a reader's trust.
+
+## What the output does not mean
+
+- A green CI badge is against the PR's **own** base branch. If that is not the base you are merging onto, it says nothing — the report will say it is being ignored.
+- "Mergeable with assisted resolution" is **not** a clean merge. Show the saved resolution diff and let a human decide.
+- File-overlap components find conflicts cheaply; they do not prove two changes are independent. A whole-repo test run can fail on changes that share no file.

mergeset-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

mergeset-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
+# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
+# transport (the default below) needs a tag from a release after 0.2.14 —
+# older tags don't declare that secret and GitHub then rejects the
+# workflow at parse time.
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    # Transport: named secrets, matching every other working i2mint repo. The
+    # generated default was the JSON transport (`toJSON(toJSON(secrets))`),
+    # and with it every run on this repo came back `action_required` with no
+    # jobs and could not even be re-run. Original comment follows.
+    #
+    # Transport: this repo's whole `secrets` context, serialized into the one
+    # secret the reusable workflow declares. Double-encoded (toJSON twice) so
+    # the value is a single line — a multiline secret would register its `{`
+    # and `}` lines as global log masks. Any secret name works; there is no
+    # fixed list to fall outside of. (Cross-owner `secrets: inherit` does not
+    # propagate secrets, so it cannot replace this.)
+    #
+    # Note this hands EVERY secret this repo can read — including org-level
+    # ones — to the called workflow. For a minimal secret surface (only the
+    # names you list), regenerate with
+    #   wads-migrate ci-to-stub --transport named
+    #
+    # *Which* of these become job env vars — and which are required — is
+    # driven entirely by [tool.wads.ci.env] in pyproject.toml; nothing is
+    # exported unless declared there (`wads-secrets add VAR_NAME` declares
+    # one and can set its value). Non-sensitive values don't need a secret:
+    # use [tool.wads.ci.env].defaults (committed literals) or a repository
+    # *variable* (`gh variable set NAME`) — declared names fall back to
+    # repo variables automatically.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      HUGGINGFACE_TOKEN: ${{ secrets.HUGGINGFACE_TOKEN }}
+      KAGGLE_USERNAME: ${{ secrets.KAGGLE_USERNAME }}
+      KAGGLE_KEY: ${{ secrets.KAGGLE_KEY }}

mergeset-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

mergeset-0.0.2/DECISIONS.md

@@ -0,0 +1,120 @@
+# Decisions
+
+Every non-obvious choice, with the reason. Entries are append-only; when a decision is reversed, the old entry stays and the new one says what changed.
+
+## D1 — The name is `mergeset`
+
+Free on PyPI (404), `github.com/i2mint/mergeset` did not exist, and `import mergeset` shadows nothing in the stdlib or in any well-known package. It also names the exact object the tool computes: the maximal *merge sets*. Runners-up, all also free: `greenset`, `braidy`, `knitset`, `amalgo`, `lattix`, `maxmerge`. Rejected because taken on PyPI: `confluo`, `conflux`, `medley`, `plexus`.
+
+## D2 — The unit is a **change**, not a branch or a PR
+
+A change is a commit range `base..head`. Branches, pull requests and explicit commit lists are *sources* that produce changes; a PR source additionally carries metadata (number, author, title, CI status, base ref, draft flag, stack relationship) in `Change.meta`.
+
+The reason to pick one word and hold it: the same analysis has to serve "these five local branches", "these PRs updated in the last 48h", and "these cherry-picks", and if the vocabulary tracks the source then every function ends up with three names for one idea. Only the *sources* module knows the word "PR"; the solver, the log and the report never say it. Metadata rides along for weighting and reporting but the solver never reads it — that keeps the search honest and testable without a repository.
+
+## D3 — The CLI adapter is `cw`, not `argh`
+
+The spec asked for `argh`. `argh` is LGPL-3.0-or-later and is being removed fleet-wide (per the `python-dispatching` skill), so this package uses `cw`, which is MIT with zero runtime dependencies. The durable part is `mergeset/cli.py::_dispatch_funcs` — an SSOT list of plain functions — and only the last line binds it to an adapter, so this decision costs one line to reverse and the same list is what a future HTTP or MCP surface would consume.
+
+## D4 — The evaluation log is the single source of truth, and it is append-only JSONL
+
+`.mergeset/evaluations.jsonl`, one JSON object per evaluated set. Everything else — the conflict set, the known-good/known-bad closure, the merge plan, both reports — is *derived* and re-derivable, so a report can be regenerated without re-running anything and a crashed run resumes for free.
+
+Two consequences worth naming:
+
+- The monotone closure is computed lazily from the rows, never materialized. Materializing it would mean writing `2**|S|` implied facts for every passing set.
+- The persistence seam is one keyword (`store`): anything with `append(jdict)` and `__iter__` works, so an in-memory log (tests), a `dol` store, or a database table are all drop-ins. The default is a plain file because the default must work with no dependency at all.
+
+## D5 — Monotonicity is a prior, not an invariant, and violations are reported rather than smoothed over
+
+The theory says good sets are downward-closed. Reality disagrees in two ways: a change can contain the *fix* that makes another change work (so a superset of a bad set passes), and flaky tests break closure outright. `EvaluationLog.monotonicity_violations()` detects the contradiction and `analyze` surfaces it as a loud note on the report instead of silently trusting a wrong inference. `flake_tolerant(validate, retries=n)` is the cheap mitigation; the honest answer is telling the user their result is not trustworthy.
+
+## D6 — Cost ordering is the architecture
+
+The pipeline is ordered by price, and nothing expensive runs until everything cheap has had its say:
+
+1. **free** — a change whose own CI is already red against its base is a conflict of size one;
+2. **milliseconds** — pairwise `git merge-tree --write-tree` finds textual conflicts with no worktree and no checkout (this is why git >= 2.38 is a hard requirement, checked up front with a fixable error message);
+3. **milliseconds** — file-overlap connected components split one `2**n` search into several small independent ones, whose answers combine by Cartesian product;
+4. **minutes each** — only then the real merge-and-test oracle.
+
+Each of 1–3 can be switched off by one keyword, because each embeds an assumption (see D7) that may not hold for a given repository.
+
+## D7 — File-overlap decomposition is an assumption, and it is opt-out
+
+Two changes touching disjoint file sets provably cannot conflict *textually*. They can still conflict *semantically* — change A adds a caller of a function change B deletes, in a file A never touched. The decomposition is on by default because the speedup is enormous and the failure mode is rare, and it is `decompose=False` away from being off. It is written down here rather than buried, because it is the one place where the tool can be confidently wrong.
+
+## D8 — Assisted merges are always flagged, never silently clean
+
+An AI resolver may attempt a conflicted merge, under a policy that is deliberately narrow: mechanical conflicts only (both sides added imports, both appended to a changelog, adjacent independent edits, regenerable lockfiles), and an explicit refusal whenever resolving would require guessing which behaviour is correct. Any set that merged this way is recorded with `merge.assisted = True` and the resolution diff saved, and it is marked in both reports. A merge that needed a machine's judgement is a different fact from a merge that was clean, and the report must never conflate them.
+
+## D9 — Weights mean "cost of dropping this change"
+
+The hitting set is weighted so that when something must be dropped, the tool drops the *cheapest* work. Default weight is `1 + log1p(lines changed)`: bigger changes are worth more, log-shaped so one huge branch cannot dominate. Overridable with any `Change -> float`, and PR metadata (labels, author, age) is right there in `change.meta` for a policy that wants it.
+
+## D10 — The oracle returns a record, not a bit
+
+Every evaluation returns which tests failed, which files they live in, the merge order used, the conflicting paths and the duration. The solver uses the merge outcome's attribution to aim `quickxplain` at the changes actually implicated instead of halving blindly, and the report can say *why* two changes conflict rather than only *that* they do. Returning a bit would have been simpler and would have thrown away the most useful thing an expensive run produces.
+
+## D11 — Merge order is deterministic and recorded
+
+Order should not matter when merges are clean. When it does matter, the run must still be reproducible, so `merge_order` sorts stacked changes parent-first and otherwise smallest-first (which surfaces cheap conflicts early), and the order used is stored on every log row.
+
+## D12 — Only *new* local branches are ever created
+
+`create_integration_branch` refuses to touch a branch that already exists unless explicitly forced, and nothing in the package pushes. This is a hard safety boundary, not a default: the tool is pointed at repositories where existing branches are other people's in-flight work.
+
+
+## D13 — `git merge-tree` is always chained through base (found by TEST)
+
+`git merge-tree A B` merges at `merge-base(A, B)`. When two candidates were cut at different times — one is stale — that merge base is older than the base we actually care about, and the base branch's own commits are reported as conflicts. Measured by the TEST workstream on a real 15-PR set: the naive pairwise sweep found **13 conflicting pairs where only 2 were real**, eleven false positives from a single stale branch.
+
+Every git operation now goes through `gitops.merge_sequence`, which merges onto base one change at a time in the object database (`merge-tree --write-tree acc head` → `commit-tree`). A pleasant consequence: a conflicted set costs milliseconds and never touches the filesystem, and a clean set yields a real commit, so the worktree step becomes a checkout rather than a sequence of merges.
+
+## D14 — Validation is an ordered sequence of named stages (found by TEST)
+
+Real projects do not have "the test command". On the repository TEST measured, `pnpm run build:cosmos` is a *prerequisite* of testing — without it seven test files fail to collect — so a validator that ran only the test command would report a false failure. And the expensive step is not the tests (9 s) but the install (33 s), which only needs to run when the lockfile moves.
+
+So a validator is a list of `ValidationStage(name, command, fingerprint=, required=)`. The failing stage's name is prefixed onto every failure id, keeping "failed to build" distinguishable from "tests failed" in the log; a fingerprinted stage re-runs only when its inputs change; and `reuse_worktree=` keeps one tree for the whole run so the install is amortized. Lint is a non-required stage by default, matching how the repository's own CI gates.
+
+## D15 — Stacks are a forest, and the constraint lives in the core (found by TEST)
+
+TEST's framing, adopted verbatim: **a valid candidate set is downward-closed under the parent relation**. Not "a prefix of a chain" — stacks branch, so siblings share a parent. Four consequences, all in `mergeset/stacks.py`: close a set before evaluating it; drop a change's whole descendant cone when dropping it; merge only the *tips*, since a tip brings its ancestors (15 changes became 6 merges); and weight a change by its cone, or the hitting set will drop a stack root believing it dropped one small PR. On the observed forest this cut the search space from 32768 subsets to 576.
+
+Shrinking must respect the closure too. QuickXplain proposes arbitrary subsets, and an arbitrary subset of a stack is a fiction: `{577, 587}` and `{575, 577, 587}` and `{575, 576, 577, 587}` all produce the same merged tree, so TEST's log recorded two duplicate evaluations under different labels. The solver now closes every subset before evaluating it, which both makes the log honest and collapses those onto one cache entry.
+
+## D16 — A forge's CI verdict is only trusted when the bases agree (found by TEST)
+
+GitHub reported PR #602 as `MERGEABLE` / `CLEAN` while it would not merge onto `main` at all — because GitHub was evaluating it against its own base branch, which had moved on. `analyze` compares each change's `base_ref` against the base being merged onto and ignores the forge's signal when they differ, saying so in the report. TEST rates this the single highest-value cheap check in the run: it excluded one change and its whole cone before any test.
+
+## D17 — "Could not run the experiment" is not "the experiment failed" (found by TEST)
+
+TEST passed a bad `reuse_worktree` and got a confident report: *Plan 1 — merge 0 of 15 · 24 expensive evaluations spent · complete*. Every checkout error had been recorded as a textual merge conflict. Three changes:
+
+- `MergeOutcome.reason` is `'conflict'` or `'error'`, and only a conflict may enter the conflict set.
+- An error produces `Verdict.ERROR`, and the search **aborts** on the first one. Continuing past an untestable evaluation manufactures conflicts out of infrastructure problems.
+- `reuse_worktree` is validated (absolute path, real worktree) with an error message naming the fix — the original failure was passing `True` to an `Optional[str]`.
+
+The tell in the bad reports was that `conflicting_files` was empty; a real textual conflict always names files.
+
+## D18 — The base is evaluated before anything else
+
+One evaluation of the empty set, on base alone. If the base does not validate, every subsequent failure is meaningless and "nothing can be merged" gets reported as a finding rather than as the misconfiguration it is. It would also have caught an earlier run where `detect_runner` classified a TypeScript repository as pytest — it checked for a `tests/` directory before looking at `package.json` — and ran pytest in it for twelve evaluations. `detect_runner` now ranks manifests above directory names, and the default validator refuses to guess rather than running the wrong command.
+
+## D19 — File-overlap components are a search strategy, not a soundness claim (found by TEST)
+
+The original version combined per-component results and presented the combination as an answer. TEST produced the counterexample: `{#579, #631}` is a real conflict spanning two components — #631's drift test asserts that committed schema artifacts match TypeScript sources, and #579 edits those sources while touching none of #631's files. No evaluated subset had ever contained both, so the tool recommended a 13-change plan that fails.
+
+Decomposition is sound for *textual* conflicts and unsound for anything a whole-repo run can see: generated artifacts, barrel exports, snapshots, type checks, project-wide lint. It is kept, because finding a conflict inside a small component is finding it cheaply — but it now only *seeds*. The components are searched first, and then a global search runs with every conflict they found already known, so it starts nearly finished. A validator may opt out by declaring `validate.component_local = True` (as `merge_only_validation` does), and the "combine freely" claim was removed from the report unless that declaration is present.
+
+## D20 — The oracle's failure output attributes blame (fixtures from TEST)
+
+`mergeset/attribution.py` mines a failure for the changes it implicates, using three signals in increasing order of strength: every path in the failure block (source frames included, not just the failing test's file); the changes that touched those paths; and — decisively — the identifiers the output names, matched against each candidate's *added* diff lines.
+
+The third signal is not a refinement. In TEST's `{#579, #631}` case the failing test lives in a file #631 added, while the culprit #579 shares no file with it, so file-level attribution accuses the innocent change; only matching `pointColorHopDirection` / `pointColorHopSeeds` / `TraversalDirectionType` against the diffs finds #579. In the `{#577, #587}` case four suites fail to *collect*, so there are no test ids at all — just a stack trace whose actionable frame is a source file. Both fixtures are committed under `notes/fixtures/` and are the tests.
+
+Attribution is only ever a *hint*: it narrows the shrink, and a wrong hint costs one wasted check before falling back to unguided halving. It never decides a verdict.
+
+## D21 — An empty log is still a log
+
+`log = log or EvaluationLog(...)` silently discarded a caller-supplied log, because `__len__` makes an empty one falsy — on the first run, which is the run where it matters. `EvaluationLog.__bool__` now returns True, and the call site tests `is None`.