{
  "schema_version": "0.1",
  "artifact_type": "prd",
  "canonical": true,
  "artifact_id": "PRD-004",
  "agent_summary": {
    "title": "Configurable Stop-hook reflections",
    "status": "approved",
    "summary": "PRD Plugin lets operators configure categorized reflection questions, invoke enabled questions from Stop hooks, and manage both categories and questions through duplicate-safe tools.",
    "last_reviewed_at": "2026-07-14",
    "load_notes": "This JSON artifact is canonical. Generate Markdown only on explicit human request."
  },
  "goals": [
    "Collect immediate, structured self-assessment about agent behavior and harness friction after work.",
    "Allow global, category, and individual-question activation without editing hook code.",
    "Provide complete, safe CRUD for reflection categories and questions."
  ],
  "non_goals": [
    "Capture or expose private chain-of-thought or hidden reasoning.",
    "Let reflections replace deterministic tests, evidence, review, or completion gates.",
    "Require a model provider or persist reflection answers into canonical project state."
  ],
  "requirements": [
    {
      "id": "PRD-REQ-025",
      "priority": "must",
      "summary": "Define one reflection configuration with a global toggle, Stop-hook toggle, maximum questions, categorized questions, and independent category/question activation.",
      "source_ids": ["REQ-090"],
      "acceptance_ids": ["PRD-ACC-029", "PRD-ACC-030"],
      "status": "approved"
    },
    {
      "id": "PRD-REQ-026",
      "priority": "must",
      "summary": "A Stop hook must select enabled questions deterministically and prompt one bounded reflection pass without creating an infinite Stop loop.",
      "source_ids": ["REQ-090"],
      "acceptance_ids": ["PRD-ACC-031", "PRD-ACC-032"],
      "status": "approved"
    },
    {
      "id": "PRD-REQ-027",
      "priority": "must",
      "summary": "Ship default behavior-quality, corrective-action, retry-opportunity, and harness-friction questions based on the operator examples.",
      "source_ids": ["REQ-090"],
      "acceptance_ids": ["PRD-ACC-033"],
      "status": "approved"
    },
    {
      "id": "PRD-REQ-028",
      "priority": "must",
      "summary": "Provide list/create/update/delete operations for categories and questions, including activate/deactivate, stable IDs, validation, and duplicate prevention.",
      "source_ids": ["REQ-090"],
      "acceptance_ids": ["PRD-ACC-034", "PRD-ACC-035"],
      "status": "approved"
    },
    {
      "id": "PRD-REQ-029",
      "priority": "must",
      "summary": "Deliver equivalent reflection configuration, hook behavior, tools, docs, and validation to supported downstream hosts.",
      "source_ids": ["REQ-090"],
      "acceptance_ids": ["PRD-ACC-036"],
      "status": "approved"
    }
  ],
  "non_functional_requirements": [
    {
      "id": "PRD-NFR-013",
      "summary": "The hook is stdlib-only, bounded, fail-open on malformed config or I/O failure, and emits only valid host hook protocol output.",
      "source_ids": ["REQ-090"]
    },
    {
      "id": "PRD-NFR-014",
      "summary": "Reflection prompts request concise conclusions and improvement actions, never private reasoning traces, secrets, or unbounded narrative.",
      "source_ids": ["REQ-090"]
    },
    {
      "id": "PRD-NFR-015",
      "summary": "Reflection is disabled by default and remains independent from deterministic completion, evidence, and autonomous Stop-guard decisions.",
      "source_ids": ["REQ-090"]
    }
  ],
  "acceptance_criteria": [
    {"id": "PRD-ACC-029", "summary": "Direct JSON configuration can enable or disable all reflection, Stop reflection, each category, and each question.", "requirement_ids": ["PRD-REQ-025"]},
    {"id": "PRD-ACC-030", "summary": "Invalid, duplicate, empty, or over-limit reflection configuration is rejected by management tools and reported by validation.", "requirement_ids": ["PRD-REQ-025", "PRD-REQ-028"]},
    {"id": "PRD-ACC-031", "summary": "The first eligible Stop emits a bounded reflection prompt; the immediately following Stop is allowed so reflection cannot recurse forever.", "requirement_ids": ["PRD-REQ-026"]},
    {"id": "PRD-ACC-032", "summary": "Disabled, empty, malformed, worker, or opted-out reflection paths allow Stop without crashing or writing canonical state.", "requirement_ids": ["PRD-REQ-026"]},
    {"id": "PRD-ACC-033", "summary": "Defaults include the five operator-requested behavior and harness-friction themes in clear categories.", "requirement_ids": ["PRD-REQ-027"]},
    {"id": "PRD-ACC-034", "summary": "CLI and MCP operations can list, create, edit, activate, deactivate, move, and delete questions, and manage categories.", "requirement_ids": ["PRD-REQ-028"]},
    {"id": "PRD-ACC-035", "summary": "Question creation allocates collision-free RFQ IDs and all mutations are atomic and preserve unrelated configuration.", "requirement_ids": ["PRD-REQ-028"]},
    {"id": "PRD-ACC-036", "summary": "Cross-host parity, installer, package, config, tool-list, and hook tests prove downstream delivery.", "requirement_ids": ["PRD-REQ-029"]}
  ],
  "dependencies": [
    "Supported hosts must expose Stop or session-idle hook output to the agent.",
    "The existing PRD Plugin MCP server and downstream script installer remain the management delivery surfaces."
  ],
  "open_questions": [],
  "traceability": {
    "source_ids": ["REQ-090"],
    "request_ids": ["REQ-090"],
    "architecture_ids": ["ARCH-COMP-020", "ARCH-COMP-021", "ARCH-COMP-022", "ARCH-COMP-023"],
    "implementation_task_ids": ["IMP-TASK-037", "IMP-TASK-038", "IMP-TASK-039", "IMP-TASK-040", "IMP-TASK-041"],
    "tracking_ids": ["TRK-087"],
    "health_ids": []
  }
}