# Human decision context

CARBON treats human decision context as an optional evidence layer near the end
of a verification workflow. It is designed for the decisions that code, tests,
and automated evaluators cannot reliably make for themselves: intent, customer
value, risk appetite, domain assumptions, experience and trust, consequence,
and accountability.

## Boundary

Human context is neither a generic requirements interview nor a sign-off
checkbox. CARBON asks a question only when its answer could change an oracle,
test priority, test-safety boundary, readiness interpretation, confidence
qualification, or release decision. It should prefer five excellent questions
over twenty ceremonial ones.

The question set is generated from the project, active scope, prior CARBON
plans, run results, findings, missing evidence, and any already recorded
answers. Questions remain durable under
`.carbon/human/decision-context.json` until answered. A subsequent smaller run
must not silently discard an open question.

## Examples of decision-changing gaps

- The requested behavior works, but no artifact identifies the customer outcome
  or the evidence that proves it was achieved.
- A team asks for release confidence, but the code does not reveal whether the
  decision is a demo, internal trial, staged rollout, or production launch.
- Authentication, payment, privacy, or a severe finding exists, but the code
  cannot define which outcome is unacceptable even once or who absorbs harm.
- A data/API flow has plausible syntactic checks but lacks the domain invariant,
  exceptional case, reconciliation rule, or operational fallback an expert
  would expect.
- A UI works mechanically but has no accountable judgment about credibility,
  confusion, surprise, trust, or fit in the real workflow.
- An AI feature has a good aggregate result but no human decision about unsafe
  populations, unacceptable mistakes, escalation, or approval authority.

## Confidence semantics

CARBON always reports the observed technical evidence it has. Missing human
context never becomes a failed test and does not stop a confidence calculation.
Instead, the result receives an explicit qualifier: it does not cover
unrecorded intent, risk appetite, taste, consequence, domain judgment, or
accountability. An answer guides planning and interpretation; it never turns
unobserved behavior into a pass or transfers release authority to CARBON.

## Persistence and privacy

The durable file is project-local and mode `0600`. It must not contain
credentials, access tokens, or unrelated personal data. `carbon_human_context`
provides `generate`, `status`, `answer`, `comment`, and `report`. `answer`
requires an explicit `HUM-*` question ID and a user-provided response; it can
also record one of the explicitly returned quick-option IDs. `comment` can be
attached to any question or the overall project decision.

## Interactive report workspace

`generate`, `answer`, and `comment` open a protected local CARBON Human
workspace beside the coding-agent chat. It is intentionally a decision canvas,
not a generic quiz: it shows why every question matters, uses compact
multiple-choice decision starters where a common answer exists, preserves room
for nuance, and displays the current evidence qualifier. Every save writes the
local context, refreshes a durable branded HTML snapshot, and makes the answer
or note available to the next CARBON plan, confidence, readiness, risk, or
persona workflow. CARBON never infers an answer from silence.
