Enterprise AI that reaches production.

// Every finding an agent emits is typed, evidenced and refutable.
// No free-form prose reaches a customer report.
{
  "id": "fnd_01J8…",
  "class": "functional-blocker | comprehension | trust | accessibility",
  "severity": "critical | major | minor",
  "claim": "One sentence. Falsifiable. No hedging.",

  // L0 — the deterministic anchor. A fact, not an opinion.
  "outcome_grounded": {
    "expected_state": "invoice.status == 'sent'",
    "observed_state": "invoice.status == 'draft'",
    "source":         "system-of-record"
  },

  // L2 — the skeptic must fail to refute it, not merely agree.
  "adversarial": {
    "verdict":   "survived",
    "refutation": null,
    "tier":      ">= generating tier"
  },

  // L3/L4 — nondeterminism converted into a statistic.
  "reproduction":  { "k": 5, "recurred": 4, "frequency": 0.8 },
  "corroborated_by": ["run_b21", "run_b44"],
  "confidence":      0.86,

  // Auditability: anyone can re-derive this conclusion later.
  "evidence": ["screen_014.png", "dom_014.txt", "trace_014.jsonl"],
  "manifest": "run_2026-08-11T09:14Z / commit 4f2a9c1"
}

# Delegated autonomy — what an agent may decide alone,
# and where it must stop and ask a human. Bounded authority
# is what makes autonomy acceptable to a risk function.

## Decide alone
- implementation detail inside an approved spec
- naming, structure, test cases, refactors behind a green suite
- retry while each attempt adds a new evidence-backed hypothesis

## Stop and ask — hard gates
- money, auth, tenancy, personal data, destructive migration
- anything that changes a contract another system depends on
- scope growth beyond the approved brief
- repeated identical failure with no new hypothesis  # the loop-breaker

## Verification rule
- reviewer tier >= builder tier on every critical path
- a cheaper model never approves a stronger model's change
- one clean post-fix round is required before close

## Durable state
- the git-tracked ledger is the source of truth, not the transcript
- every wave closes with: decision, evidence, exact SHA, next action
- if the tooling disappeared tomorrow, the ledger is still readable
  in a text editor  # no lock-in, by construction

// Shipping AI to a non-technical user who is personally liable for
// what the software does. Four rungs decide how far the AI may go —
// and the top of the ladder is "never act", not "act carefully".

export const AI_TRUST_RUNG_VALUES = [
  "find",       // surface it
  "check",      // verify completeness, readiness, risk
  "draft",      // write it — a human signs it
  "never_act",  // money, access, roles, legal, privacy, external effect
] as const;

// Anything touching money, access, roles, official records, privacy or
// the outside world resolves to never_act — a classification the
// surrounding code enforces.
export function inferAiTrustRung(input): AiTrustRung {
  if (/money|access|role|official|privacy|external|legal/.test(v)) return "never_act";
  if (/draft|minutes|reply|message|certificate/.test(v))          return "draft";
  if (/check|review|readiness|completeness|risk|gap/.test(v))      return "check";
  return "find";
}

// The part that makes it real: a build-time guard over the product's
// OWN user-facing copy. The interface cannot claim the AI decided,
// sent, approved or collected anything — the suite fails first.
export function assertNoAiAuthorityOverclaim(text: string): void {
  for (const pattern of AUTHORITY_OVERCLAIM_PATTERNS) {
    if (pattern.test(text)) {
      throw new Error(
        "AI copy must not imply legal, money, access, official, " +
        "privacy, or external-effect authority."
      );
    }
  }
}

# Cost-aware routing. Capability where it changes the outcome,
# cheap where it does not, deterministic code where a model
# adds risk without adding judgement.

deterministic:
  use:    [ledger-moves, filtering, joins, dedup, validation]
  why:    "faster and auditable; a model here is pure downside"

volume_tier:
  use:    [bounded-inventories, fixtures, format-conversion]
  never:  approving critical-path logic

workhorse_tier:
  use:    [implementation, research, debugging, standard-review]
  effort: medium   # escalate only where evals show real gain

frontier_tier:
  use:    [architecture, schema-design, ambiguous-decisions,
           security-privacy-money-review, cross-agent-synthesis]
  effort: high

invariants:
  - "verification tier >= generation tier on critical paths"
  - "agent count is not evidence of progress"
  - "reuse green proof only for the same SHA, scope and config"
  - "benchmark every route change; one variable at a time"