{
  "schema_version": "1.0",
  "baseline": "A-document-note-system-v1",
  "updated_at": "2026-04-19",
  "owner": "session_a",
  "purpose_th": "Periodic AI review model สำหรับ note backlog · กำหนดสิ่งที่ AI ต้องดู · overdue rules · flag updates · state ของระบบจริง",
  "purpose_en": "Periodic AI review model for the document note backlog. Describes what an automated sweep checks, what signals it emits, and what it is permitted to mutate. This is a MODEL document — no scheduler is running today. Any claim that AI sweep is 'live' is false at this baseline.",
  "honest_state": "MODELED · NOT WIRED. No cron. No queue. No automated triage. This document is the spec a future Batch 6+ implementation must conform to. An operator can still act on it manually by reading notes across all documents and applying the rules below by hand.",
  "sweep_cadence_target": {
    "proposed": "daily 07:00 Asia/Bangkok (aligned with 12E.1 locked cadence)",
    "current": "none · manual",
    "next_phase": "Batch 6+ · consume this model"
  },
  "inputs": [
    {
      "source": "localStorage keys matching ds.notes:*",
      "current_state": "browser-local only · per-device",
      "planned_upgrade": "server table ds.document_note once persistence layer ships"
    },
    {
      "source": "git log for each doc_id's source file",
      "purpose": "Resolve linked_change_ref claims — verify the referenced commit actually touched the document"
    },
    {
      "source": "document_index.json + index-catalog.json",
      "purpose": "Resolve doc_id → title + owner + status · enrich the sweep report"
    }
  ],
  "checks": [
    {
      "id": "C-01",
      "name": "Open backlog per document",
      "rule": "Count notes with status in ('open','triaged','in_review','planned','in_progress') per doc_id.",
      "emits": "open_count per doc",
      "threshold": "Flag docs with > 10 open notes as 'attention-needed'."
    },
    {
      "id": "C-02",
      "name": "Overdue triage",
      "rule": "Notes in 'open' state with created_at older than 14 days.",
      "emits": "overdue_triage list",
      "action_suggestion": "Transition to 'triaged' with auto-comment OR escalate priority."
    },
    {
      "id": "C-03",
      "name": "Stale in_progress",
      "rule": "Notes in 'in_progress' state with last_action_at older than 21 days.",
      "emits": "stale_progress list",
      "action_suggestion": "Owner review · either advance to 'done' (with linked_change_ref) or revert to 'planned'."
    },
    {
      "id": "C-04",
      "name": "Done without linked_change_ref",
      "rule": "Notes in 'done' state with linked_change_ref=null and resolved_at older than 7 days.",
      "emits": "unverified_done list",
      "action_suggestion": "Owner attaches the commit hash / PR id, or revert to 'in_review'."
    },
    {
      "id": "C-05",
      "name": "Repeated requirement themes",
      "rule": "Cluster notes by note_type + keyword similarity across docs · surface top 5 recurring themes.",
      "emits": "theme_cluster_report",
      "action_suggestion": "Lift into a cross-doc planning page if theme repeats in ≥5 documents."
    },
    {
      "id": "C-06",
      "name": "Docs missing core metadata",
      "rule": "Cross-reference each doc with the Universal Document Shell 18-section spec. Flag docs that lack Key Point / Summary / Glossary / References / Checklist / Notes section.",
      "emits": "metadata_gap_report per doc",
      "action_suggestion": "Auto-file a content-gap note on each missing section."
    },
    {
      "id": "C-07",
      "name": "Docs missing glossary or references",
      "rule": "Separate pass on two highest-value sections.",
      "emits": "glossary_missing_list · references_missing_list"
    },
    {
      "id": "C-08",
      "name": "Reading-flow orphans",
      "rule": "Docs with no 'recommended before-reading' AND no 'recommended next-reading' entries · likely not connected to the reading graph.",
      "emits": "orphan_list"
    },
    {
      "id": "C-09",
      "name": "High-priority untouched",
      "rule": "Notes with priority='P0' and status in ('open','triaged') for > 3 days.",
      "emits": "p0_alert",
      "action_suggestion": "Immediate escalation · page an owner."
    },
    {
      "id": "C-10",
      "name": "Reopened oscillation",
      "rule": "Notes that have cycled between 'done' and 'open' ≥ 3 times.",
      "emits": "oscillation_list",
      "action_suggestion": "Owner session required — likely spec gap not a bug."
    }
  ],
  "allowed_mutations_by_ai": {
    "permitted": [
      "Create new note with created_by_type='AI' (content-gap / metadata / linkage type only)",
      "Attach AI-generated triage summary as a comment (future field: comments[])",
      "Suggest priority change via a new note, never mutate priority directly on an existing human note"
    ],
    "forbidden": [
      "Change status on notes where created_by_type='human' without an audit trail",
      "Delete any note for any reason",
      "Modify linked_change_ref on a note it did not create"
    ]
  },
  "report_shape": {
    "run_id": "sweep-<ISO-timestamp>",
    "run_at": "ISO-8601 UTC",
    "scope": "all | specific_docs[]",
    "metrics": {
      "docs_scanned": "integer",
      "notes_total": "integer",
      "notes_open": "integer",
      "notes_done": "integer",
      "notes_deferred": "integer",
      "p0_alerts": "integer",
      "stale_progress": "integer",
      "unverified_done": "integer"
    },
    "per_doc_highlights": "array",
    "theme_clusters": "array",
    "recommended_actions": "array"
  },
  "cadence_triggers_planned": [
    "daily 07:00 Asia/Bangkok run",
    "on-demand via operator command (planned endpoint POST /api/docs/notes/sweep)",
    "pre-release gate (before any phase closeout)"
  ],
  "non_goals_this_batch": [
    "Running the sweep automatically",
    "Producing actual reports",
    "Mutating any notes",
    "Cross-device sync"
  ],
  "cross_references": {
    "schema":         "docs/assets/notes/document_note_schema.json",
    "status_matrix":  "docs/assets/notes/document_note_status_matrix.json",
    "examples":       "docs/assets/notes/document_note_examples.json",
    "planning_doc":   "docs/planning/document-note-system.html"
  }
}