> ## Documentation Index
> Fetch the complete documentation index at: https://honest-scholar.science/llms.txt
> Use this file to discover all available pages before exploring further.

# honest-scholar — Decision Log (ADRs)

> MADR-style Architecture Decision Records for the honest-scholar plugin. Each records the context, the options considered, the rejected alternatives and why, and…

MADR-style Architecture Decision Records for the `honest-scholar` plugin. Each records
the context, the options considered, the rejected alternatives **and why**, and
links to the spec section + grounding digest. Captured 2026-07-17 during the
design session; the reasoning here is not reconstructable from the specs alone.
Migrates to the plugin's `decisions/` alongside `resources/references/`.

> Purpose beyond the record: this log is the raw material for a planned blog
> post / paper explaining the skills and the reasoning behind them — the intent
> is eventually to write that *using* `honest-scholar` (`paper-synthesis` + `defend`).

| ADR                                                        | Decision                                                                                                          | Status   |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
| [0001](/decisions/0001-separate-plugin-repo)               | Package the workflow as a standalone plugin, not in-mononet                                                       | accepted |
| [0002](/decisions/0002-scientific-scope-only)              | Scientific scope only; engineering delegated via a contract                                                       | accepted |
| [0003](/decisions/0003-agency-principle)                   | Agency principle — assistants, not researchers                                                                    | accepted |
| [0004](/decisions/0004-understanding-principle-and-defend) | Understanding principle + the `defend` skill                                                                      | accepted |
| [0005](/decisions/0005-three-level-mirror)                 | Three-level mirror; thesis as a partial mirror                                                                    | accepted |
| [0006](/decisions/0006-two-skills-per-level)               | Two pipeline skills per level (generate/resolve)                                                                  | accepted |
| [0007](/decisions/0007-literature-one-skill-two-modes)     | `literature` = one skill, scout/position modes                                                                    | accepted |
| [0008](/decisions/0008-literature-bib-plus-triage)         | Literature registry = standard bib + triage sidecar                                                               | accepted |
| [0009](/decisions/0009-dataset-thin-manifest)              | `dataset` one skill + thin `datasets.yml` (reject DVC/DataLad/lakeFS)                                             | accepted |
| [0010](/decisions/0010-storage-tiers)                      | Tiers A/B/C by (license × access); mirror ≠ redistribution grant                                                  | accepted |
| [0011](/decisions/0011-rclone-mirror-sha256)               | rclone private mirror; SHA-256 authoritative fixity                                                               | accepted |
| [0012](/decisions/0012-shared-substrate)                   | Shared asset substrate — share the mechanism, not the file                                                        | accepted |
| [0013](/decisions/0013-experiment-backend-contract)        | Experiment-backend *contract* + pluggable backend                                                                 | accepted |
| [0014](/decisions/0014-progress-cross-cutting)             | `progress` cross-cutting; semantic roll-up; anti-Goodhart                                                         | accepted |
| [0015](/decisions/0015-defend-cross-cutting)               | `defend` cross-cutting; guardrail stop-and-confirm; teaching; non-grading                                         | accepted |
| [0016](/decisions/0016-mentor-personas)                    | Mentor personas author-selectable; no personality inference                                                       | accepted |
| [0017](/decisions/0017-research-init-one-skill)            | `research-init` one skill, init/adopt modes                                                                       | accepted |
| [0018](/decisions/0018-git-native-source-of-truth)         | Git-native plain text as source of truth; cross-repo out of scope                                                 | accepted |
| [0019](/decisions/0019-public-plugin-visibility)           | Public plugin, named `honest-scholar`                                                                             | accepted |
| [0020](/decisions/0020-bib-format-csl-json)                | CSL-JSON source of truth; BibTeX exported on demand                                                               | accepted |
| [0021](/decisions/0021-thesis-gate-per-gap-confirmation)   | Thesis gate — per-gap acknowledged confirmation                                                                   | accepted |
| [0022](/decisions/0022-license-apache-2.0)                 | License the plugin under Apache-2.0                                                                               | accepted |
| [0023](/decisions/0023-engineering-delegation-contract)    | Delegate engineering via a contract, not a named tool                                                             | accepted |
| [0024](/decisions/0024-tooling-package-and-bootstrap)      | Supporting tooling = one package (Typer CLI, optional MCP) + markdown `ensure-tooling` bootstrap                  | accepted |
| [0025](/decisions/0025-disclosure-and-citation-growth)     | Honest AI-use disclosure + citation as the growth mechanism (auto-proposed by `paper-synthesis`)                  | accepted |
| [0026](/decisions/0026-independent-versioning-compat-pin)  | Independent plugin/package versioning with a compatibility pin                                                    | accepted |
| [0027](/decisions/0027-release-driven-oidc-publish)        | Publish via GitHub Releases + PyPI Trusted Publishing (OIDC, no tokens)                                           | accepted |
| [0028](/decisions/0028-100-percent-coverage-gate)          | 100% statement + branch coverage gate on the package                                                              | accepted |
| [0029](/decisions/0029-api-key-handling)                   | Unified API-key handling — a CLI-managed JSON store (not `.env`), stdin writes, scoped in-memory env for children | accepted |
| [0030](/decisions/0030-docs-site-mintlify)                 | Docs site on Mintlify, published from a generated docs repo to `honest-scholar.science`                           | accepted |

Format: MADR (Markdown Any Decision Records). Deciders: Davor Runje (with Claude).