record_human_answer

Category: intel
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Ingests a human answer for a chunk: resolves open questions and reopens the chunk for enrichment. Call it to unblock context waiting on human input.

Arguments

Required: chunk_ref, answer_text.

Optional: question_id.

chunk_ref.
answer_text. Note: Appended to the chunk body, so the source hash changes and the chunk becomes assessable again.
question_id. Note: Answers one question when given; answers all open questions for the chunk when omitted. Omitted (not null) to answer all.

Result

Object with chunk_id, new_state, previous_state, questions_resolved count, and source_hash_updated flag.

Boundaries

Operates inside the selected profile boundary. Frozen chunks refuse answers.

Lifecycle / side effects

Marks addressed questions answered, appends the answer to the chunk body with a fresh source hash, moves awaiting_human or uncertain chunks back to enrichable, and records resolution provenance, a history event, and a run-history entry. All-or-nothing.

Errors

Missing chunk_ref or answer_text rejected by validation (multi-missing shape when both absent). Unknown chunk returns not-found. Frozen chunks return a cannot-record error payload.

Example

{
  "answer_text": "This covers the bridge sync workflow.",
  "chunk_ref": "<uuid>"
}

Result shape:

{
  "chunk_id": "<uuid>",
  "new_state": "enrichable",
  "previous_state": "awaiting_human",
  "questions_resolved": 2,
  "source_hash_updated": true
}