Skip to content

Record architecture decisions: add docs/adr from fleet evidence #55

Description

@cpitzi

The fleet-wide ADR reconstruction (2026-08-13) recovered this repo's architectural decisions from commit history, issues/PRs, CLAUDE.md, incident reports, and session archives. This issue asks for them to be recorded in-repo as decision records.

Deliverable

  • docs/adr/README.md — an index of the entries, opening with a one-paragraph provenance note: reconstructed 2026-08-13 from repo history and fleet records, dates are the original decision dates.
  • One docs/adr/0001-<slug>.md per decision below.
  • A short "Architecture decisions" line in the main README linking the directory.

Format

Match the existing fleet ADR style (see drosera/docs/adr/0001-*.md / solidago/docs/decisions/0001-*.md): # ADR-NNNN: <title>, **Status:** Accepted (<original date>; reconstructed 2026-08-13), then Context, Decision, Alternatives, Consequences. The Alternatives section must contain (a) the alternatives actually recorded in the evidence, and (b) one or two options explicitly marked "retrospective — not considered at the time", each honestly assessed (worse, better, or lateral — and why). Do not present retrospective options as if they were weighed historically.

Ground rules

  • Verify every anchor below (issue/PR numbers, files, dates) against this repo before asserting it in a doc. If something doesn't check out, drop it or state it as uncertain — never copy claims blind.
  • Public repo: add no LAN IPs, hostnames, or network topology beyond what this repo already discloses.
  • Scope: only the ADR files + the README link. No other changes; adjacent problems get their own issue.
  • Open a PR with Closes #<this issue>. Do not arm auto-merge — these PRs wait for human review.

Decisions to record

  1. The product is a versioned prompt program. prompts/v<N>-auditor.md, new integer per revision, old versions kept for diffing/reproduction; the multi-model pipeline decomposition designed (docs/architecture.md, Implement pipeline decomposition (Opus / Sonnet / Haiku stages) #11) but deliberately unimplemented. Retrospective: a scripted Crossref/API tool (better determinism; wrong genre — prompt-engineering-as-product is the exhibit, and live web search is the verification surface by design).
  2. Paired evaluation sets as regression gates. Adversarial-30 (detection) + the real-article corpus (feat(test-sets): add real-article clean corpus for false-positive calibration #42, false positives); "a revision that flags more on both is just noisier"; the clean corpus caught v5 over-penalization (Scoring formula: D×3 base cost makes the headline score misleading for large reference lists #43: a real article scored ~22, corrected to 96 in v6); baselines committed per version (feat(baseline): establish v5 production baseline — regression gate, H9 functional check #41/feat(baseline): v6 production baseline — H10 functional check, regression gate, scoring calibration #46).
  3. Four-tier risk classification over a continuous score; non-accusatory language as a design requirement. "Continuous scores invite gaming and false precision"; verdicts never accuse ("predatory" is not a finding).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions