{
  "schema_version": "0.1",
  "artifact_type": "architecture",
  "canonical": true,
  "artifact_id": "ARCH-004",
  "agent_summary": {
    "title": "Stop-hook reflection architecture",
    "status": "approved",
    "summary": "A shared fail-open hook reads a validated reflection section from config, selects enabled questions, and requests one bounded agent reflection pass. Python CLI and MCP CRUD edit the same config under existing atomic/locking rules.",
    "last_reviewed_at": "2026-07-14",
    "load_notes": "This JSON artifact is canonical. Generate Markdown only on explicit human request."
  },
  "context": "Stop hooks already coordinate autonomous continuation, drift, reporting, and archive behavior across Claude, Codex, and opencode. Reflection must compose with them without becoming a completion authority or recursion source.",
  "principles": [
    "One config truth shared by direct JSON, CLI, MCP, and hooks.",
    "Stable IDs and atomic mutations; no agent scans for the next question ID.",
    "One reflection pass per Stop cycle, concise conclusions only, fail open on every error."
  ],
  "components": [
    {"id": "ARCH-COMP-020", "summary": "Reflection configuration model", "responsibility": "Store global policy, category metadata, and RFQ question records in .prd_plugin/config.json with strict validation.", "requirement_ids": ["PRD-REQ-025", "PRD-REQ-027"], "interface_ids": ["ARCH-IF-013"]},
    {"id": "ARCH-COMP-021", "summary": "Reflection Stop hook", "responsibility": "Select enabled questions, build a privacy-safe bounded prompt, and use a local pending marker to block exactly one Stop pass.", "requirement_ids": ["PRD-REQ-026", "PRD-NFR-013", "PRD-NFR-014"], "interface_ids": ["ARCH-IF-014"]},
    {"id": "ARCH-COMP-022", "summary": "Reflection management CLI", "responsibility": "Expose category/question list, create, update, enable/disable, move, and delete operations over the canonical config.", "requirement_ids": ["PRD-REQ-028"], "interface_ids": ["ARCH-IF-015"]},
    {"id": "ARCH-COMP-023", "summary": "Reflection MCP facade", "responsibility": "Expose bounded list/create/update/delete tools that reuse server locking, atomic writes, and RFQ allocation.", "requirement_ids": ["PRD-REQ-028", "PRD-REQ-029"], "interface_ids": ["ARCH-IF-016"]}
  ],
  "interfaces": [
    {"id": "ARCH-IF-013", "summary": "reflection configuration", "producer": "operator, prd_reflections.py, or MCP", "consumer": "reflection Stop hook", "contract": "enabled, on_stop, max_questions_per_stop, categories[{id,name,enabled,questions[{id,text,enabled}]}]"},
    {"id": "ARCH-IF-014", "summary": "Stop reflection protocol", "producer": "prd_reflection.py", "consumer": "host agent", "contract": "On first eligible Stop emit decision=block with numbered questions and answer constraints; on the next Stop consume the local marker and allow termination."},
    {"id": "ARCH-IF-015", "summary": "Reflection CLI", "producer": "scripts/prd_reflections.py", "consumer": "operator or automation", "contract": "JSON-capable list/create/update/delete commands for category and question entities; enable/disable are update operations."},
    {"id": "ARCH-IF-016", "summary": "Reflection MCP tools", "producer": "mcp/server.cjs", "consumer": "host agent", "contract": "prd_reflection_list, prd_reflection_create, prd_reflection_update, and prd_reflection_delete with entity-specific schemas and server-generated RFQ IDs."}
  ],
  "data_state_model": {
    "canonical_configuration": ".prd_plugin/config.json#reflection",
    "question_id_prefix": "RFQ",
    "ephemeral_stop_state": ".prd_plugin/local/reflection/",
    "canonical_answer_storage": "none"
  },
  "decisions": [
    {"id": "ARCH-DEC-013", "summary": "Keep categories and questions inside the reflection config section.", "rationale": "This makes direct JSON, CLI, and MCP operate on one source of truth and avoids another state file.", "source_ids": ["PRD-REQ-025", "PRD-REQ-028"]},
    {"id": "ARCH-DEC-014", "summary": "Use four entity-aware MCP CRUD tools rather than separate tools for every verb and entity.", "rationale": "Four tools provide full CRUD for both categories and questions with a smaller discoverable surface.", "source_ids": ["PRD-REQ-028"]},
    {"id": "ARCH-DEC-015", "summary": "Use a consume-on-next-Stop local marker to bound reflection to one pass.", "rationale": "A reflection answer changes the transcript, so transcript fingerprints would recurse; a pending marker is deterministic and resets for the next user-driven Stop cycle.", "source_ids": ["PRD-REQ-026", "PRD-NFR-013"]},
    {"id": "ARCH-DEC-016", "summary": "Do not persist answers in canonical PRD Plugin state.", "rationale": "Harnesses can observe the agent response, while canonical storage would mix subjective model evaluation with project truth and raise privacy risk.", "source_ids": ["PRD-NFR-014", "PRD-NFR-015"]}
  ],
  "risks": [
    {"id": "ARCH-RISK-010", "summary": "Reflection blocks Stop repeatedly or conflicts with the autonomous guard.", "mitigation": "Consume-on-next-Stop marker, independent decisions, configurable opt-out, and cross-hook integration tests.", "status": "mitigated"},
    {"id": "ARCH-RISK-011", "summary": "Questions elicit private reasoning, secrets, or performative unbounded prose.", "mitigation": "Prompt asks for concise verdicts, observable evidence, and actions only; explicit prohibition on secrets and hidden reasoning.", "status": "mitigated"},
    {"id": "ARCH-RISK-012", "summary": "Direct JSON edits create duplicate IDs, malformed categories, or excessive prompts.", "mitigation": "Strict hook/CLI/MCP validation, RFQ allocation, category/question uniqueness checks, bounded selection, and gate diagnostics.", "status": "mitigated"}
  ],
  "validation_strategy": [
    "Unit-test config validation, deterministic selection, marker lifecycle, privacy wording, malformed-input fail-open, and worker opt-out.",
    "Unit-test CLI and MCP CRUD, duplicate rejection, collision-safe RFQ allocation, atomicity, and unrelated-config preservation.",
    "Parity-test Claude, Codex, opencode, shared hooks, skeleton configuration, installer scope, and package contents.",
    "Run full workflow, state, release, traceability, drift, and CHML audit loops before shipping."
  ],
  "traceability": {
    "source_ids": ["PRD-REQ-025", "PRD-REQ-026", "PRD-REQ-027", "PRD-REQ-028", "PRD-REQ-029", "REQ-090"],
    "implementation_task_ids": ["IMP-TASK-037", "IMP-TASK-038", "IMP-TASK-039", "IMP-TASK-040", "IMP-TASK-041"],
    "tracking_ids": ["TRK-087"],
    "health_ids": []
  }
}