{
  "schema_version": "1.0",
  "baseline": "A-document-note-system-v1",
  "updated_at": "2026-04-19",
  "owner": "session_a",
  "purpose_en": "Lifecycle state matrix for document notes. Defines allowed transitions, terminal states, and UI expectations per state. Consumers (document-shell.js + any future backend) must respect this matrix — no ad-hoc state jumps.",
  "purpose_th": "Matrix กำหนดการเปลี่ยนสถานะของ note · state ใดเปลี่ยนเป็นอะไรได้ · terminal state · UI color · ใช้กับ client + backend เมื่อขึ้น",
  "states": [
    {
      "id": "open",
      "label_en": "Open",
      "meaning_en": "Newly submitted. Awaiting triage.",
      "ui_color": "blue",
      "next_allowed": ["triaged", "deferred", "rejected", "planned", "in_progress", "done"],
      "default_entry": true,
      "terminal": false
    },
    {
      "id": "triaged",
      "label_en": "Triaged",
      "meaning_en": "Reviewer has acknowledged and classified. Not yet scheduled.",
      "ui_color": "purple",
      "next_allowed": ["in_review", "planned", "deferred", "rejected", "in_progress"],
      "terminal": false
    },
    {
      "id": "in_review",
      "label_en": "In review",
      "meaning_en": "Under active evaluation by an owner. Decision pending.",
      "ui_color": "amber",
      "next_allowed": ["planned", "in_progress", "deferred", "rejected", "done"],
      "terminal": false
    },
    {
      "id": "planned",
      "label_en": "Planned",
      "meaning_en": "Scheduled for a future batch. Assigned to a phase or milestone.",
      "ui_color": "amber",
      "next_allowed": ["in_progress", "deferred", "rejected"],
      "terminal": false
    },
    {
      "id": "in_progress",
      "label_en": "In progress",
      "meaning_en": "Work has started. An edit or change is being produced.",
      "ui_color": "pink",
      "next_allowed": ["done", "deferred", "rejected"],
      "terminal": false
    },
    {
      "id": "done",
      "label_en": "Done",
      "meaning_en": "Resolved. linked_change_ref SHOULD point to the commit / PR that addressed it.",
      "ui_color": "green",
      "next_allowed": ["open"],
      "reopen_allowed": true,
      "terminal": true,
      "sets_resolved_flag": true
    },
    {
      "id": "deferred",
      "label_en": "Deferred",
      "meaning_en": "Valid but deliberately postponed. Not rejected — will be revisited.",
      "ui_color": "gray",
      "next_allowed": ["open", "planned", "in_progress", "rejected"],
      "terminal": false
    },
    {
      "id": "rejected",
      "label_en": "Rejected",
      "meaning_en": "Declined after review. Reason SHOULD be captured in body or linked_change_ref.",
      "ui_color": "rose",
      "next_allowed": ["open"],
      "reopen_allowed": true,
      "terminal": true,
      "sets_resolved_flag": true
    }
  ],
  "forbidden_transitions": [
    "done → triaged (must reopen first)",
    "rejected → planned (must reopen first)",
    "deferred → done without in_progress (should explicitly go through planned/in_progress for an audit trail)"
  ],
  "terminal_behaviour": {
    "visual": "Note card gets class .ds-note.resolved · title gets strikethrough · actions menu reduced to 'Reopen' and 'Delete'.",
    "sweep_consequence": "Periodic AI sweep skips terminal notes unless older than 90 days and linked_change_ref is null (stale-closed audit)."
  },
  "open_item_definition": "status in ('open', 'triaged', 'in_review', 'planned', 'in_progress'). Used by summary counter and AI sweep.",
  "cross_references": {
    "schema":        "docs/assets/notes/document_note_schema.json",
    "sweep_model":   "docs/assets/notes/document_note_sweep_model.json",
    "examples":      "docs/assets/notes/document_note_examples.json"
  }
}