Merge pull request #63 from StepenkoAnatoli/docs/eudr-dates

Point the kit at something it knows nothing about, and watch it fail first

Author: StepenkoAnatoli

docs/decisions/2026-09-22-eudr-dates/.gitattributes

@@ -0,0 +1,10 @@
+# The corpus's line endings are integrity, not style.
+#
+# A capture's body hash is taken over the LF bytes the collector fetched. git's smudge
+# filter rewrites every text file on a default Windows checkout (core.autocrlf=true), so
+# without this file the whole corpus fails `body-unmodified` on arrival with nothing
+# actually wrong with it. This file outranks a reader's core.autocrlf. See ADR-0020.
+
+research/raw/* text eol=lf
+*.jsonl text eol=lf
+research/*.md text eol=lf

docs/decisions/2026-09-22-eudr-dates/.gitignore

@@ -0,0 +1,27 @@
+node_modules/
+.DS_Store
+
+# Credentials never belong in a research project (AGENTS.md Rule 6). Note that
+# `firecrawl env` writes the key into .env, which is why the rule says never to run it
+# inside a repository.
+.env
+.env.*
+*.pem
+*.key
+
+# The Firecrawl CLI saves scrape output into .firecrawl/ in whatever directory it runs
+# from. That is a vendor cache, not evidence - the kit's own captures live in
+# research/raw/ with a ledger entry behind each one.
+.firecrawl/
+
+# The kit's local review logs are not evidence.
+research/raw/.usage.jsonl
+research/raw/.failures.jsonl
+research/raw/.diagnostics.jsonl
+research/raw/.fetches.lock
+
+# The chain IS evidence and must travel. The explicit negation is here so a broader
+# dotfile rule added later cannot silently exclude it - this repository lost its ledger
+# exactly that way once.
+!research/raw/.fetches.jsonl
+!research/overrides.log

docs/decisions/2026-09-22-eudr-dates/AGENTS.md

@@ -0,0 +1,131 @@
+# Research-first project bootstrap
+
+Agent instructions for this project. Read this before planning, designing, or building
+anything here.
+
+## How this project works: two phases, two roles
+
+**Phase 1 - research (this kit).** Close every blocking unknown with fetched primary
+sources, then pass the gate. The output is a briefing, not code: `research/DISCOVERY.md`
+(the contract), `research/EVIDENCE.md` (claims with cached pages behind them), and
+`research/BRIEF.md` (the handoff). Phase 1 never writes product code.
+
+**Phase 2 - build (someone else's job).** A builder - another agent, a different model, or
+a human - takes `research/BRIEF.md` plus `research/` and implements. They should not need
+to re-research anything: if they do, phase 1 was incomplete, and the fix is to collect the
+missing fact rather than to let the builder guess it.
+
+The gate is the handoff point. Before it passes, phase 2 does not start.
+
+## Two machines, two roles
+
+The role is machine config - `role: "collector" | "builder"` in
+`~/.agents/research-kit.config.json`, default `collector`; declare it with
+`node ~/.agents/research-kit/bin/install-hooks.mjs --role builder`.
+
+| | **collector** (the operator's PC) | **builder** (a sandbox, a CI box, a laptop) |
+|---|---|---|
+| holds | the Firecrawl key | no key, no Firecrawl egress |
+| runs | `decompose.mjs`, `research.mjs` | `handoff.mjs`, `preflight.mjs`, the build |
+| a missing key is | a **FAIL** | **informational** |
+| must | push `research/raw/` including its dotfiles | **not collect** - the collection CLIs refuse (exit 2) |
+
+**If you are on a builder machine and there is no brief: you do not collect.** A page
+fetched by hand is not evidence in this kit, and a builder that "re-collects" a missing
+page forges a corpus instead of reporting a gap. Name the missing fact instead.
+
+A builder's first command is:
+
+```
+node ~/.agents/research-kit/bin/handoff.mjs
+```
+
+The remedy depends on the cause, and the command says which: something that did not
+travel is the collector's to push (`git add -f research/raw/`, dotfiles included);
+a corpus that travelled whole and was rewritten on checkout here is fixed **here**, with
+`.gitattributes`, and costs no credits.
+
+## Starting in the wrong place: ask which project, do not hunt for it
+
+The project is the **current working directory**. The kit takes no project argument and
+never will. If the cwd is not the project the operator means - the kit's own repo, a
+parent folder, an unrelated checkout - **ask which project**, and wait. Do not search the
+filesystem, do not infer it from a name, do not look it up on a remote. Searching a
+person's disk to guess his intent reads directories nobody authorised, and the question
+it replaces takes one line.
+
+Signals: no `AGENTS.md`, no `research/` directory, or a `research/` corpus plainly about
+something else. An existing corpus about another topic is the signal doing its job.
+
+## Resuming after an interruption: resume, do not restart
+
+The gate is a pure function of repository state, so orient from disk before touching
+anything. `doctor.mjs` and preflight answer *where this project is*; the last commit
+report and `docs/ARCHITECTURE.md` say *what was happening and why*; `git status` answers
+what is unfinished, and its uncommitted changes are the interrupted task - partial and
+unverified, work in progress, never state to trust. The corpus is already collected and
+spent credits are not spent again.
+
+## Rule 1 - research first, then build
+
+The sequence is decompose -> contract -> collect -> gate -> brief.
+
+0. **Decompose** (collector machine): `node ~/.agents/research-kit/bin/decompose.mjs --topic "<topic>"`
+   drafts `research/MAP.md` seeded with the universal checklist. The tool contains no
+   judgment. Mark every row COVERED (citing U-## rows), DISMISSED (reason required), or
+   GAP.
+1. **Write the intent** in `research/DISCOVERY.md` under `## Build intent`, and enumerate
+   the blocking unknowns FROM the map.
+2. **Collect**: `node ~/.agents/research-kit/bin/research.mjs --plan research/plan.json`. Prefer the page
+   that *owns* the fact over any write-up about it.
+3. **Rewrite** each auto-extracted `Finding` cell into a real claim, keeping the `Raw`
+   cell pointing at the cached page.
+4. **Gate**: `node ~/.agents/research-kit/bin/preflight.mjs`. **Do not start building until it prints
+   PASS.** Evidence must be *fetched*, not typed, and by a named transport.
+5. **Hand off**: write `research/BRIEF.md`.
+
+There are exactly three overrides - `git commit --no-verify`, a deliberate
+`research/GATE_OFF`, and a repository-local `core.hooksPath` - and all three are recorded
+in `research/overrides.log`. If you take one, say so in your reply.
+
+## Rule 2 - questions are for intent, never for facts
+
+At most **3** questions, once, up front, and only about things no document can answer. If
+a question's answer is in public documentation, it is a research task. **Never answer
+"insufficient info" and stop.**
+
+## Rule 3 - known unknowns are allowed, silence is not
+
+Mark a genuinely unreachable fact `KNOWN-UNKNOWN` and write the day-one verification step
+in the `Evidence` cell. An unlabeled gap is the failure mode this project exists to
+prevent.
+
+## Rule 4 - source quality
+
+`P` primary/official carries the design. `S` secondary is context. `L` lead-only is a
+hint, never proof. Never invent a citation. Flag contradictions instead of averaging them.
+
+## Rule 5 - cost discipline
+
+Every scrape spends credits. Plan the queries in `research/plan.json` first, reuse the
+cache (`--refresh-days`), and check the budget with `node ~/.agents/research-kit/bin/research.mjs --status`.
+
+## Rule 6 - secrets
+
+The key lives in the CLI config or the environment. Never write it into this repository.
+
+## The standing protocol
+
+Five rules for how work here is committed and recorded. Documentation, not enforcement:
+no check judges prose, because a gate that judges prose is a gate that will be wrong.
+
+1. **Architecture map current in the same commit.** A commit touching a declared code
+   path (`research/kit.json`) stages `docs/ARCHITECTURE.md` with it. Enforced - and a
+   prompt, not a proof: the gate checks the map was *staged*, not that it is *current*.
+2. **Commit report: five named parts** - what changed / why / what it touched / what you
+   verified / what you got wrong and fixed. The got-wrong line is not optional; if
+   nothing was gotten wrong it is written as "nothing to report".
+3. **An ADR for any choice with a rejected alternative**, dated, with the reason a future
+   explorer would need to avoid re-suggesting it.
+4. **One commit per task - the revert test.** `git revert <sha>` undoes it alone.
+5. **A red suite stops work**, reported immediately and alone, **with the cwd recorded**.

docs/decisions/2026-09-22-eudr-dates/START_HERE.md

@@ -0,0 +1,43 @@
+# Start here
+
+A **decision project** (ADR-0030), and the first one in this repository about something
+other than the kit's own plumbing. Read `research/BRIEF.md`.
+
+**The question:** when does the EU Deforestation Regulation actually apply?
+
+**The answer:** large and medium operators from **30 December 2026**; micro and small from
+**30 June 2027** — *unless* already covered by the EU Timber Regulation, in which case the
+earlier date. Postponed twice.
+
+## Why it exists
+
+To test whether the kit produces research a builder could act on **in a domain it knows
+nothing about**. Every other corpus here is about GitHub, Node, MCP or this kit's vendors,
+where the reviewer already knows enough to catch a bad answer.
+
+A prior was written down **before collecting**: "30 December 2025 … 30 June 2026,
+confidence high." That is a year wrong on both dates, and the corpus corrected it.
+
+## The part worth reading even if you do not care about deforestation
+
+**The first collection returned eight captures and none of them were about the EUDR** — SEC
+filings, CFPB regulations, California water boards. The search had matched the word
+"regulation."
+
+That corpus would have passed every structural check: eight captures, verifying hash chain,
+recorded transports, no partial grades. **No check asks whether the evidence is about the
+topic.** `research/BRIEF.md` has the isolation showing it was the search provider, not the
+query and not the kit.
+
+## Verifying it
+
+From **this** directory:
+
+```
+cd docs/decisions/2026-09-22-eudr-dates
+node ..\..\..\research-kit\bin\preflight.mjs
+node ..\..\..\research-kit\bin\handoff.mjs
+```
+
+As of 2026-09-22: `PASS  0 blocking, 0 warning(s), 15 passing`, passes `--strict`, and
+`handoff OK - 8 ledger entries, chain verifies`.

docs/decisions/2026-09-22-eudr-dates/docs/ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# ARCHITECTURE - the map of the code
+
+What each module owns, the seams between them, and which decision governs each. This is
+a map of the **code**, not of the research: `research/MAP.md` is the topic map - a
+different artifact with a different job, judged by a different check.
+
+The rule this map lives by: a commit touching a **declared code path** (declared in
+`research/kit.json`, defaulting to `src` / `lib` / `bin` / `scripts` / `app`) carries
+this file's update in the **same commit**. The commit gate refuses such commits without
+it.
+
+What the rule proves is deliberately modest: the gate checks this file was **staged**
+with the code, not that it is current - a whitespace edit satisfies it. That makes a
+stale map a deliberate act rather than mere forgetting. A prompt, not a proof.
+
+## The one picture
+
+```
+_Replace this with the shape of the thing you build: the entry points, the modules
+they reach, and the seams between them._
+```
+
+## Modules - what each one owns
+
+| Module | Owns | Governed by |
+|---|---|---|
+| _module_ | _the one concept it is responsible for_ | _ADR or decision_ |
+
+## The seams
+
+_Where modules touch, what is injectable, and why testing can stay offline._
+
+## Current shape, for the record
+
+_Counts and invariants a reader can check against the code: how many checks, how many
+adapters, which defaults._

docs/decisions/2026-09-22-eudr-dates/research/BRIEF.md

@@ -0,0 +1,87 @@
+# Brief - when does the EUDR actually apply?
+
+- **Date:** 2026-09-22
+- **Gate:** PASS - 0 blocking, 0 warnings, 15 passing, and it passes `--strict`
+- **Corpus:** 8 captures, 8 ledger entries, chain verifies
+- **Collected by:** run `35723908266` via `bin/collect-remote.mjs`, search pinned to `firecrawl-cli`
+
+## The answer
+
+From the European Commission, which sets and publishes these dates:
+
+| operator | applies from |
+|---|---|
+| large and medium operators | **30 December 2026** |
+| micro and small operators | **30 June 2027** |
+| micro and small operators **already covered by the EU Timber Regulation** | **30 December 2026** |
+
+Application has been postponed **twice**: from 30 December 2024, then from 30 December 2025.
+
+The third row is the part a summary loses. Being small is not sufficient for the later date
+— an operator already inside EUTR scope is on the earlier one. Neither the prior registered
+before this collection nor a general web search on the same question surfaced it. Only the
+Commission page states it.
+
+## What this exercise was actually testing
+
+Not the EUDR. **Whether the kit produces research a builder could act on, in a domain it
+knows nothing about** — chosen because every previous corpus here is about GitHub, Node, MCP
+or the kit's own vendors, where the reviewer already knows enough to catch a bad answer.
+
+A prior was registered in writing **before any collection**, so the corpus could contradict
+it. It did.
+
+> "30 December 2025 for large and medium operators, and 30 June 2026 for micro and small
+> enterprises. Confidence: high."
+
+**That is a year wrong on both dates.** The prior also said, correctly, that a second
+postponement decided after May 2026 could not be known from memory. There was one. The
+corpus supplied exactly the thing the reviewer could not have.
+
+## The finding that matters more than the dates
+
+**The first collection returned nothing relevant at all**, and the gate could not tell.
+
+Run on the default search path, the same topic produced eight captures: SEC exempt
+offerings, two CFPB regulations, federalregister.gov, California water boards, an SEC crypto
+press release, regulations.gov, and an EU climate effort-sharing page. **Zero about
+deforestation.** The search had matched the word "regulation" and returned US financial
+regulators.
+
+That corpus would have passed every structural check in the kit. It had eight captures, a
+verifying hash chain, recorded transports, no partial grades. `preflight` had nothing to say
+about it, because **no check asks whether the evidence is about the topic.** The only thing
+standing between that corpus and a confident wrong brief was a human reading the URLs.
+
+Isolated by re-running the identical query string through the other provider:
+
+| search provider | candidates | on topic |
+|---|---|---|
+| SerpApi (the default, because a key is present) | 8 | **0** |
+| Firecrawl | 17 | **17** |
+
+Not the query — a general web search on the same string returns the Commission, the European
+Parliament press room, and the legislative train. Not the kit's code — both ran the same
+path. The provider failed, and the auto-detect rule picks it.
+
+## What the corpus is honest about
+
+- **U-1 and U-3 rest on the Commission alone**, recorded as accepted single-witness
+  judgements rather than papered over. On the dates an authority sets, a second party can
+  only report.
+- **Wikipedia is cited with a warning attached.** Its infobox strikes through both superseded
+  dates, which is what establishes two postponements. Its **body text still asserts the old
+  pair** — the exact dates the registered prior held. One page, current in its structured
+  data and a year stale in its prose. It is cited for the sequence and for nothing else.
+- **Five of eight captures are law-firm and vendor commentary.** They agree with the
+  Commission and none of them is cited for a claim, because agreement with the authority is
+  not independent confirmation of it.
+
+## Limits
+
+- **One collection, one provider, one day.** The dates have moved twice; nothing here
+  predicts whether they move again, and the corpus would not know if they did.
+- **No legal reading.** This is the date obligations begin, not advice about what they
+  require of any particular operator.
+- **The EUTR carve-out is quoted, not interpreted.** What counts as "already covered by the
+  EU Timber Regulation" is a scope question this corpus did not ask.

docs/decisions/2026-09-22-eudr-dates/research/DISCOVERY.md

@@ -0,0 +1,36 @@
+# Discovery Contract - when does the EUDR actually apply?
+
+Started 2026-09-22.
+
+## Build intent
+
+A compliance question with a date answer, chosen deliberately from a domain this project
+knows nothing about, to test whether the kit produces research a builder could act on
+rather than research that merely passes its own checks.
+
+"Done" is the operative application dates as of today, from the authority that sets them,
+with the amending instrument named.
+
+**A prior was registered before any collection, so the corpus could contradict it.** It did.
+The prior said 30 December 2025 for large operators and 30 June 2026 for micro and small
+enterprises, at high confidence, with an explicit note that a second postponement decided
+after May 2026 could not be known. There was a second postponement.
+
+## Unknowns
+
+| ID | Unknown | Why it blocks the build | Status | Evidence |
+|---|---|---|---|---|
+| U-1 | What are the operative EUDR application dates today? | Any compliance plan is scheduled off this date. A year wrong in either direction is either wasted spend or a missed obligation | CLOSED | E-01: the Commission states it directly - large and medium operators **30 December 2026**, micro and small operators **30 June 2027**, and micro and small operators already covered by the EU Timber Regulation **30 December 2026** [single-witness: the European Commission is the authority that sets and publishes these dates, so a second party can only report them. One of the secondary rows in this corpus demonstrates what that reporting is worth - its own prose still carries the superseded pair while its structured data is current] |
+| U-2 | How many times has application been postponed, and by what instrument? | A date that has already moved twice is a date that may move again. Knowing the mechanism is how a plan stays correct rather than lucky | CLOSED | E-06 records the sequence: 30 December 2024 struck through, then 30 December 2025 struck through - **two postponements**, not one. E-08 names the outcome of the second in its title: "EU Deforestation Regulation application postponed to 30 December 2026" |
+| U-3 | Does the smallest-operator deferral apply to everyone small? | A carve-out that catches an operator a year early is exactly the kind of detail a summary drops | CLOSED | E-01: **no.** Micro and small operators get 30 June 2027 **unless already covered by the EU Timber Regulation**, in which case the earlier date applies. Neither the registered prior nor a general web search surfaced this; only the Commission page states it [single-witness: the EUTR carve-out is stated only by the Commission page. A general web search on the same question did not surface it at all, which is the point - a summary drops the exception and keeps the headline date] |
+
+## Questions for the human (maximum 3)
+
+1. None for this corpus. The dates are stated by the authority and carry an amending
+   instrument. If anything is wanted next it is a watch on further postponement, which is a
+   cadence question rather than a research one.
+
+## Already decided
+
+- Nothing. This project exists to test the kit on an unfamiliar domain, not to support a
+  build.