feat: AI-authoring mode (--author) with base-validation anti-hallucination filter (#1)

Adds 'einsiedler --author --repo <r> --base <ref> [--engine <cmd>]': an LLM
proposes fast-check invariants for changed files, and every proposal is
validated against the BASE version of the code so a hallucinated invariant
(wrong about existing behavior) is discarded before it can produce a false
signal. Surviving, base-validated invariants run against HEAD; falsifications
there are real behavior changes worth review.

Pipeline (einsiedler/author-mode.mjs): derive changed source files (core/diff),
AI-author via ask-opencode (Qwen, free/local) with ask-codex fallback and a
--engine override, parse+normalize+syntax-check the returned module, base-
validate in a clean git worktree, head-run survivors via the fast-check lane,
report fail-closed stats. Type-aware generator prompt guards the README false-
positive lesson. v2 note: marmorkrebs mutation-filter left out of this first cut.

- einsiedler/author-mode.mjs: full pipeline + pure helpers (export detection,
  LLM-output extraction, import normalization, syntax check).
- einsiedler/cli.mjs: --author/--engine/--out-dir/--no-keep-authored wiring;
  existing --modules/--validate unchanged.
- fixtures/author-demo/mock-engine.mjs: deterministic engine for a hermetic
  smoke test (canned 3-invariant module: 1 survivor, 1 head-falsifier, 1
  base-hallucination).
- test/einsiedler-author.test.mjs: pure-helper unit tests + end-to-end pipeline
  smoke test (real git worktree, mock engine, asserts hallucination filtered and
  HEAD behavior change surfaced, exit 2).
- README: AI-authoring section, flags, worked run, honest limitations.
- package.json lint: check author-mode.mjs + mock-engine.mjs.

Author: anagnorisis2peripeteia

README.md

@@ -11,13 +11,17 @@ in `*.eks.mjs` modules against symbols you name. Each module exports a `properti
 function returning `{ name, coversSymbol, property }` entries — see
 `examples/sample/clamp.eks.mjs` for the shape.
 
-**Be honest about what this is:** einsiedlerkrebs is a **targeted** tool, not a
-point-and-go one. It can only test the invariants someone — a human or an AI — actually
-wrote down as `*.eks.mjs` modules. No authored properties, no coverage. Use it
-deliberately on the functions where an invariant is worth stating (parsers,
-math/clamping helpers, serialization round-trips), not as a blanket CI requirement that
-somehow "just works" the moment it's wired in. Read "Authoring good invariants" below
-before writing your first one.
+**Two ways to get invariants.** The base tool is **targeted**: it tests the invariants
+someone wrote as `*.eks.mjs` modules — no authored properties, no coverage. Use it
+deliberately on the functions where an invariant is worth stating (parsers, math/clamping
+helpers, serialization round-trips). Read "Authoring good invariants" below before writing
+your first one by hand.
+
+The **`--author` mode** (see "AI-authoring mode" below) is what makes einsiedler
+point-and-go: an LLM proposes the invariants for your changed files, and every proposal is
+**base-validated** so a hallucinated invariant (one that's simply wrong about your existing
+code) is discarded before it can produce a false signal. You still don't get magic — you
+get a validated first cut you can review and keep.
 
 ## Usage
 
@@ -49,6 +53,68 @@ einsiedlerkrebs --repo /path/to/repo --modules src/props \
 | `--allow-empty` | Treat zero exercised targets as an explicit pass (`PASS_EMPTY`) instead of `NO_PROPERTY` |
 | `--report-file <path>` | Persist the full JSON report (written before exit, survives a failing gate) |
 
+## AI-authoring mode (`--author`)
+
+Instead of hand-writing `*.eks.mjs` modules, let an LLM propose invariants for the files
+you changed — and trust them only after they've been validated against your existing code.
+
+```bash
+einsiedlerkrebs --author --repo /path/to/repo --base main
+einsiedlerkrebs --author --repo . --base main --engine "my-llm-cmd"   # custom engine
+```
+
+Pipeline:
+
+1. **Derive** — the changed source files vs `--base` (reuses `core/diff.mjs`), keeping
+   JS/TS files with plausibly-pure exported functions.
+2. **AI-author** — for each file, an LLM is asked to propose fast-check invariants as a
+   `.eks.mjs` module. The prompt demands **type-aware generators** (never untyped garbage
+   against a typed param — the false-positive lesson below) and prefers low-risk
+   never-crash / round-trip / idempotence / range invariants over risky semantic guesses.
+   The default engine is the local, free `ask-opencode` (Qwen), falling back to `ask-codex`;
+   `--engine <cmd>` overrides both (the prompt is passed as the trailing argument).
+   Authored modules are persisted to `authored/<safe-name>.eks.mjs`.
+3. **Base-validate (the anti-hallucination filter)** — each authored property is run
+   against the **base** version of the code in a clean `git worktree`. Any property that
+   **falsifies on base** is *wrong about existing behavior* — a hallucination — and is
+   **discarded**. Only base-holders survive. Fail-closed: a property that errored or ran
+   vacuously on base doesn't count either.
+4. **Head-run** — the surviving, base-validated properties run against **HEAD** via the
+   normal fast-check lane. A **falsification here is a real behavior change / bug** worth
+   review — exactly the signal the gate exists to produce.
+5. **Report** — files scanned, invariants authored, discarded-on-base (hallucinations
+   filtered), survivors, and HEAD falsifications, plus the standard fail-closed verdict.
+
+Worked run (a clean `clamp` at base, an off-by-one introduced at HEAD; invariants written
+by Qwen via `ask-opencode`):
+
+```
+✓ HELD       [clamp] [authored] never-crash: clamp(x, lo, hi) does not throw for all valid inputs
+✗ FALSIFIED  [clamp] [authored] bounds: result is within [min(lo,hi), max(lo,hi)] inclusive
+             counterexample=[0,0,0]
+=> VERDICT FALSIFIED (exit 2)
+  --- AI-authoring pipeline ---
+  files scanned=1  authored=1  invariants authored=2
+  discarded on base: 0 hallucination(s) (falsified base) + 0 unvalidatable
+  base-validated survivors=2  HEAD falsifications=1
+```
+
+| `--author` flag | Meaning |
+|---|---|
+| `--author` | Enable AI-authoring mode (requires `--repo` and `--base`) |
+| `--engine <cmd>` | Override the authoring engine; the prompt is appended as the last arg |
+| `--out-dir <path>` | Where authored `.eks.mjs` modules are written (default `authored/`) |
+| `--no-keep-authored` | Don't persist authored modules to disk |
+
+> **Limitations of this first cut.** Parsing free-form LLM output is the fragile part: the
+> engine's response is scanned for a fenced code block containing a `properties(fc)` export,
+> its import is normalized to the source, and it's syntax-checked — anything unparseable is
+> skipped (never trusted). New files have no base version, so their invariants can't be
+> validated and are discarded. Sources are imported directly, so plain ESM is the solid
+> path; TypeScript needing a real compile step degrades to a skip. A **v2** would add the
+> marmorkrebs mutation-filter (keep only invariants a mutant can actually kill, to weed out
+> trivially-true tautologies).
+
 ## Fail-closed contract
 
 - **validate-provider canary.** `fixtures/canary/canary.eks.mjs` is a deliberately false
@@ -105,8 +171,9 @@ Rules of thumb:
 
 ```
 core/            shared report shape + verdict logic (report.mjs), git diff helpers (diff.mjs)
-einsiedler/      cli.mjs, fast-check-lane.mjs
-fixtures/        validate-provider canary (fixtures/canary/canary.eks.mjs)
+einsiedler/      cli.mjs, fast-check-lane.mjs, author-mode.mjs (the --author pipeline)
+fixtures/        validate-provider canary (fixtures/canary/canary.eks.mjs);
+                 author-demo/ — deterministic mock engine for the --author smoke test
 examples/sample/ a worked example (clamp.mjs + clamp.eks.mjs)
 scripts/         validate-provider.mjs — CI gate proving the canary is live
 test/            node:test suite