09_ai_workflows/atlas_system_update_workflow.md

Atlas document

Atlas System Update Workflow

> **용도**: 교수님이 "atlas 업데이트해줘", "atlas 시스템 갱신해줘", "atlas 동기화해줘" 등으로 요청할 때 AI가 따르는 표준 워크플로. 무엇을 점검하고, 어떤 순서로 반영하고, 어떻게 검증·보고하는지를 정의한다.

---

1. 트리거 및 범위 판단

요청을 받으면 먼저 범위를 확인한다. 애매하면 임의로 진행하지 않고 아래에서 고른다.

요청 유형판단 기준처리 범위
**전체 동기화**"전체", "시스템", "동기화"이 문서의 전 단계 실행
**부분 업데이트**특정 레이어 지정 (예: "08 업데이트")해당 레이어 + 관련 연결만
**신규 자료 반영**새 PDF/zip/문서가 함께 옴ingestion 프로토콜 먼저 → 이후 이 워크플로
**목적지 불명확**Atlas용인지 Wiki용인지 안 함**반드시 먼저 질문** (운영 규칙)

---

2. 표준 업데이트 절차 (전체 동기화 기준)

### Step 1 — 상태 감사 (Audit)

변경 감지를 위해 현재 상태를 수집한다.

점검 항목:① 00_sources/: extension별 full_text / source_notes / paper_cards / originals 수   - originals PDF 수 vs source index 대조 (미매칭/미보유 확인)② 03_papers/: 카드 수 (YAML atlas_doc_type 기준, 지원 파일 제외)③ 02/04/05 노드: Tier 1/Tier 2 수(2026-08-26 기준 127 = 29 + 98), node_tier_inventory.csv와 대조   - 노드별 필수 섹션 존재: Core idea 플레이스홀더("To be expanded") 0건, Linked nodes 100%, Key extension/supporting evidence 섹션 100%   - Migrated supporting note 블록이 있으면 consolidation 표식(Consolidation note) 확인 — 표식 없는 블록에 내용을 추가하지 않는다④ 07_visualization/: 행렬 행 수, extension_registry.csv, 최신 리포트 목록   - 엣지 무결성 3종: (a) 엣지 target이 실존 노드 파일 stem과 일치하는가 (b) 셀프루프 0건 (c) 각 카드의 related_atlas_nodes Tier 1 선언이 배치 엣지 CSV 행으로 존재하는가 — 하나라도 어긋나면 ingestion 불완료⑤ 08_teaching/: 강의 모듈 수, 인덱스 등록 상태⑥ 09_ai_workflows/: 살아있는 워크플로 vs archive⑦ 10_knowledge_outputs/: outputs_index 등록 누락 산출물 여부, stale 상태 문서, knowledge_ledger 미반영 사실⑧ html_dashboard/: 메트릭이 실제 값과 일치하는지⑨ 최근 대화/작업에서 생성·수정된 파일 목록 (업데이트 반영 누락 후보)

### Step 2 — 반영 대상 확정

감사 결과에서 **불일치·누락·신규** 항목을 리스트업하고, 무엇을 고칠지 먼저 제시한다. 대규모 변경(파일 삭제, 구조 변경)은 반드시 승인 후 진행한다.

### Step 3 — 레이어별 반영

우선순위 순서:1. 데이터층 (00_sources, 03_papers)  ← 원본·카드가 최우선2. 구조화층 (07_visualization)       ← 행렬/엣지/레지스트리3. 노드층 (02/04/05)                 ← supporting sources 섹션4. 교육층 (08_teaching)              ← 모듈·인덱스 수치 갱신5. 워크플로층 (09_ai_workflows)      ← 프로토콜이 바뀐 경우만6. 산출물층 (10_knowledge_outputs)   ← 영향받은 산출문서 stale 표기 또는 갱신, knowledge_ledger 누적7. 대시보드 (html_dashboard)         ← 항상 마지막에 재구축 (생략 금지)

각 레이어 규칙:

  • **데이터층**: PDF stem 파일명 유지, YAML 스키마(`atlas_doc_type`, `extension_id` 등) 준수, node tag 금지
  • **구조화층**: 행렬/엣지는 기존 컬럼 유지 + append, registry 상태 갱신
  • **노드층**: Tier 1 최소 1개 연결 강제, 연결 밀도 3~6, relation 6유형 구분. 신규/갱신 노드는 카드 YAML과 배치 엣지 CSV를 **같은 패스**에 기록한다(어긋남 방지). 노드 본문 뒤의 Migrated note 블록은 provenance이므로 갱신 금지(consolidation 표식 확인)
  • **교육층**: 수치는 반드시 registry/inventory에서 실측해 기입 (추측 금지)
  • **대시보드**: `~/.hermes/scripts/rebuild_dashboard.py` 재실행 또는 동일 로직으로 재구축

    • ### Step 4 — 검증 (Verification)

    모든 업데이트는 기계적 검증을 통과해야 한다.

    검증 체크리스트:□ 링크 전수 점검: 상대경로 참조가 실존 파일로 resolve되는가□ 수치 일치: 문서에 적힌 수 = 실측 수 (카드 수, 행 수, 노드 수, 페이지 수)□ YAML 정합: 신규 카드의 필수 필드 존재, Tier 1 연결 ≥ 1□ 깨진 노드 참조 0건: 존재하지 않는 노드 경로 없음□ 산출물 인덱스: 새 산출문서가 outputs_index.md에 등록됨, 신규 사실이 knowledge_ledger.md에 기록됨□ 대시보드 링크: rendered 링크가 실제 파일로 연결, fallback 0건□ rendered 신선도: 그래프/문서 링크가 가리키는 rendered_md가 현재 소스 .md 내용을 닮았는가  (검증법: rendered HTML에서 태그 제거 후 순수 서술 행만 프로브 — 마크다운 기호 행(`- `, `**`)은 <li>/<strong> 변환되어 미스매치로 오탐)□ 노드 정책 준수: "카드 Tier1 선언 = 배치 엣지 행" 동시성 검증 PASS (PROJECT_NODE_POLICY.md §2026-08-26 audit)□ GitHub 동기화: html_dashboard 변경분이 ekvm80/ecc-research-atlas origin/main에 푸시됨□ 원본 PDF: originals 수 = index의 available 수, SHA-256 기록

    ### Step 5 — 보고 (Reporting)

    아래 형식으로 보고한다.

    1. 감사 결과 (발견된 불일치/누락)2. 수행한 변경 (레이어별)3. 검증 결과 (체크리스트 통과 여부)4. 남은 이슈 / 다음 단계 제안

    대규모 작업은 `07_visualization/` 또는 해당 레이어에 리포트 파일을 남긴다.

    ---

    3. 부분 업데이트 시나리오

    시나리오절차
    **원본 PDF 추가 도착**`original_pdf_matching_protocol.md` → Step 4~5
    **새 extension zip 도착**`new_extension_ingestion_protocol.md` → 노드 remap → Step 3(2~6번) → Step 4~5
    **책 관련 자산 변경**`victor_li_book_citation_protocol.md`의 자료 계층 갱신 → 대시보드
    **논문 카드 대량 수정**YAML 스키마 검증 → 행렬/엣지 동기화 → Step 4~5
    **산출물 생성 요청** (연대기·보고서·분석)근거 수집 → `10_knowledge_outputs/` 저장 → outputs_index 등록 + knowledge_ledger 누적 → Step 4~5
    **워크플로 정리 요청**"꼭 필요한 것 아니면 제거" 원칙: 일회성 파일은 archive로, 삭제는 승인 후

    ---

    4. 운영 규칙 (교수님 확인 사항)

    1. **Atlas vs Wiki**: 논문·자료 제공 시 목적지를 말씀 없으시면 임의 판단하지 않고 먼저 질문한다.

    2. **삭제**: 파일 삭제는 항상 목록 제시 후 승인을 받는다. 아카이브 이동은 자율 진행 가능.

    3. **extension 미지정**: 신규 논문의 extension 소속이 불명확하면 먼저 질문한다.

    4. **검증 요청**: "검증해줘" 요청 시 이 문서의 Step 4 체크리스트를 적용하고, 발견된 결함은 즉시 수정 후 재검증한다.

    5. **Extension-first 답변 (필수)**: 노드 주제 질문 시 노드 파일에서 끝내지 않고, 노드의 `## Key extension evidence` 섹션 논문 카드 + `07_visualization/*_claim_evidence_matrix.csv` 해당 노드 행까지 확인 후 답변한다 (PROJECT_NODE_POLICY.md §Extension-first answering rule).

    6. **대시보드 동시 업데이트 (필수)**: 어떤 범위의 Atlas 업데이트든 작업을 마치면 html_dashboard도 반드시 함께 갱신한다. 별도 요청이 없어도 기본 포함된다. 대시보드만 빠뜨린 채로 완료 보고하지 않는다.

    7. **GitHub 동기화 (필수)**: html_dashboard 갱신 후 `07_visualization/html_dashboard/`(git 루트)에서 아래 절차로 origin/main에 푸시한다. 생략하지 않는다.

    cd ~/Documents/Research_Knowledge/ECC_Research_Atlas/07_visualization/html_dashboardgit add -Agit commit -m "Dashboard update: <변경 요약>"git push
  • 원격: https://github.com/ekvm80/ecc-research-atlas (public, GitHub Pages 활성)
  • 푸시 1~2분 후 https://ekvm80.github.io/ecc-research-atlas/ 에 자동 반영된다. Pages 빌드 상태는 `gh api repos/ekvm80/ecc-research-atlas/pages/builds/latest --jq '.status'`로 확인한다.
  • 네트워크 사정으로 푸시가 실패하면 완료 보고에 "GitHub 미푸시"를 명시하고 다음 세션에서 재시도한다.

    • ---

    5. 07_visualization 폴더 정책

    `07_visualization/`은 시각화·구조화 데이터 전용이다 (정책 상세: `../07_visualization/README.md`).

  • **허용**: claim-evidence matrix, graph edges, 노드 인벤토리/대장, registry, timeline/map/tree/rules, html_dashboard
  • **금지**: 1회성 작업 리포트, 완료된 계획서, 백업 스냅샷을 루트에 신규 생성
  • 작업 보고는 대화 보고로 마무리하고, 파일이 꼭 필요하면 `07_visualization/archive_YYYY-MM/`에 기록
  • 살아있는 문서(README/PROJECT_RULES/08_teaching/node_inventory 등)가 참조하는 기존 리포트는 유지

    • 6. 관련 워크플로

    new_extension_ingestion_protocol.md      # 신규 extension 유입 상세original_pdf_matching_protocol.md        # 원본 PDF 매칭 상세victor_li_book_citation_protocol.md      # 책 인용 검증external_ai_pdf_processing_request_template.md  # 외부 AI 처리README.md                                # 워크플로 전체 지도