Humanities Book Plugin

학술 도서를 출처 추적 가능한 연구 스킬로 증류하고, 검증된 주장만으로 여러 저작을 비교하는 Agent Plugin입니다.

처음 사용하는 경우 사용자 가이드에서 book-to-skill과 book-research로 할 수 있는 작업, 연구 모드, 권장 실행 흐름을 확인하세요.

현재 checkout의 plugin manifest는 1.0.0 Stable입니다. schema v2의 General Nonfiction / Method & Practice, Theology, Philosophy, History, Literature & Aesthetics, Social & Political Thought 여섯 렌즈를 지원합니다. Stable Gate는 재현 가능한 release tree, 여섯 렌즈, 두 스킬, 포스트-인제스트 품질 도구를 함께 검증합니다. Theology는 Exegesis·Systematic·Historical·Practical Theology 프로필을, Literature & Aesthetics는 Aesthetics 프로필을 선택할 수 있습니다.

제공 스킬

• book-to-skill: 처리 권한이 있는 PDF, EPUB, DOCX, HTML, RTF, 텍스트를 여섯 렌즈 중 하나의 독립 템플릿으로 구조화해 source digest, segment locator, claim index를 가진 연구 스킬로 만듭니다. 대용량 책은 --chapter N으로 한 장씩 증분 처리할 수 있습니다.
• book-research: 여러 생성 도서의 source-checked claim을 조회하고, 저자 진술과 연구자 종합을 분리한 Research Packet을 작성합니다.

대용량 책 빠른 시작

대용량 책은 전체 원문을 모델 컨텍스트에 올리지 않습니다. 추출기는 원문 전체를 private evidence sidecar에 보존하고, --chapter N으로 선택한 챕터만 작업용 full_text.txt에 내보냅니다.

export BOOKS_ROOT=path/to/books

python3 skills/book-to-skill/scripts/extract.py path/to/large-book.pdf \
  --chapter 1 --mode text --no-install-missing \
  --require-rights --rights-confirmed \
  --rights-basis authorized-research-use \
  --books-root "$BOOKS_ROOT" --book-id book-a

첫 챕터는 일반 generate 절차로 도서 스킬과 schema v2 index를 만듭니다. 두 번째 챕터부터는 변경 전 baseline을 만들고 새 챕터 하나만 추가합니다.

python3 skills/book-to-skill/tools/validate_chapter_update.py snapshot \
  "$BOOKS_ROOT/book-a" --output path/to/work/ch02-baseline.json

python3 skills/book-to-skill/scripts/extract.py path/to/large-book.pdf \
  --chapter 2 --mode text --no-install-missing \
  --require-rights --rights-confirmed \
  --rights-basis authorized-research-use \
  --books-root "$BOOKS_ROOT" --book-id book-a

python3 skills/book-to-skill/tools/validate_chapter_update.py check \
  "$BOOKS_ROOT/book-a" --baseline path/to/work/ch02-baseline.json

check는 다음을 보장합니다.

• 새 챕터가 정확히 하나인지 검사합니다.
• 기존 장 파일·장 항목·claim·source·segment가 바뀌거나 삭제되지 않았는지 검사합니다.
• 새 claim이 모두 새 챕터에 속하고 최소 source-checked인지 검사합니다.
• coverage.chapters_covered가 검증된 claim을 가진 챕터만 세는지 검사합니다.

번호형 장 제목을 감지할 수 없으면 분리한 챕터 파일에 고유 --source-id와 --append-evidence를 사용합니다. 자세한 재개·실패 규칙은 챕터별 증분 처리 계약을 따릅니다.

포스트-인제스트 품질 gate

validate_chapter_update.py check는 기존 정본의 불변성을 검사하고, 포스트-인제스트 quality gate는 claim의 의미와 귀속까지 별도로 검사합니다. 새 챕터는 다음 상태를 순서대로 통과한 뒤 정본에 들어갑니다.

extracted → structured → claims-generated → quality-checked → ready → committed

품질 gate는 provenance, grounding, attribution, stance, context, atomicity를 독립적으로 판정합니다. locator가 맞더라도 claimant가 unresolved/ambiguous이거나 저자 stance·문맥·근거가 확인되지 않으면 source-checked로 승격하지 않습니다. 검증에 사용하는 evidence text map은 private 작업 위치에만 두고, report에는 claim ID·locator·상태·reason code만 남깁니다.

python3 skills/book-to-skill/tools/validate_claim_quality.py \
  "$BOOKS_ROOT/book-a" \
  --evidence-texts path/to/private/evidence-texts.json \
  --report path/to/work/quality-report.json

python3 skills/book-to-skill/tools/build_review_queue.py \
  "$BOOKS_ROOT/book-a" \
  --evidence-texts path/to/private/evidence-texts.json \
  --output path/to/work/review-queue.json

새 챕터를 정본 밖에서 staging하려면 제안된 전체 book-index.json과 claim-index.json을 먼저 준비한 뒤 다음 순서를 사용합니다. stage가 출력하는 staging directory를 check와 commit에 전달합니다.

python3 skills/book-to-skill/tools/process_chapter.py stage \
  --book-dir "$BOOKS_ROOT/book-a" \
  --chapter-id ch02 \
  --input-digest "$INPUT_DIGEST" \
  --manifest path/to/proposed/book-index.json \
  --claim-index path/to/proposed/claim-index.json \
  --chapter-file path/to/chapter-02.md

python3 skills/book-to-skill/tools/process_chapter.py check \
  --staging-dir <staging-dir> \
  --quality-report path/to/work/quality-report.json

python3 skills/book-to-skill/tools/process_chapter.py commit \
  --book-dir "$BOOKS_ROOT/book-a" \
  --staging-dir <staging-dir>

schema v2의 자유 문자열 attribution은 계속 읽을 수 있지만 새 gate에서는 claimant를 책 저자로 추정하지 않고 review 대상으로 보류합니다. 귀속 오류는 기존 claim을 덮어쓰지 말고 별도 correction으로 처리해 supersedes, 변경 이유, 이전 digest와 reviewer를 revision ledger에 남깁니다. 자세한 계약은 attribution contract, claim quality, 사용자 가이드를 참고합니다.

신학 렌즈

신학 렌즈는 역사적 기술, 저자의 승인, 본문 해석, 교의적 명제, 구성적 제안, 실천적 함의를 서로 다른 claim으로 분리합니다.

프로필	우선하는 연구 축
exegesis	성서 참조, 주해 방법, 원어, 해석학적 이동
systematic-theology	신학적 로키, 교리적 입장, 신학 방법, 권위의 출처
historical-theology	전통, 교리 발전, 교회적 맥락, 인물과 수용
practical-theology	실천, 교회적 맥락, 목회·윤리·예배의 함의

프로필은 별도 요약을 추가하지 않고 같은 장·claim 구조에 검색 축만 더합니다. 성경 인용은 곧 규범적 사용이라는 뜻이 아니며, 전통에 대한 역사적 설명은 저자의 동의를 뜻하지 않습니다.

Stable 검증에서는 공개 도서 스킬과 private evidence sidecar를 분리합니다. sidecar는 books root의 .humanities-book-evidence/<book-id>/에만 두며, 공개 JSON에는 절대 경로를 기록하지 않습니다. validation_id는 locator report와 Research Packet을 연결하는 결정적 식별자입니다. 원본 digest를 확인할 수 없으면 source-checked 승격과 deep 검증이 실패합니다.

주요 게이트 명령:

python3 skills/book-to-skill/tools/validate_locators.py <books-root> --report <report-dir>
python3 skills/book-to-skill/tools/validate_chapter_update.py check <book-dir> \
  --baseline <workdir>/chapter-baseline.json
python3 skills/book-to-skill/tools/validate_research_packet.py <packet.json> \
  --locator-report <report-dir>

챕터별 처리 중 generated claim만 있는 장은 검색 후보일 뿐 verified coverage에 포함되지 않습니다. 부분 coverage인 책의 claim을 중심 종합에 사용하면 Research Packet의 limitations에 누락 장과 영향을 기록해야 합니다.

렌즈·claim subtype·typed facet의 정본은 skills/book-to-skill/book_to_skill/lenses.py와 각 렌즈 템플릿에 있습니다. Catalog는 --lens와 --facet, claim catalog는 여기에 --type·--subtype·--claimant·--discourse-voice·--stance·--resolution을 제공합니다. 정정 이력까지 감사하려면 --include-superseded를 사용합니다.

mcp.json은 아직 제공하지 않습니다. 두 스킬은 번들 Python 스크립트만 사용하며, 설치 위치나 특정 호스트의 전역 경로를 탐색하지 않습니다.

개발과 릴리스

릴리스는 소스 트리를 직접 배포하지 않습니다. 허용 목록 빌더로 별도 트리를 만든 뒤 검증합니다.

python3 scripts/build_plugin.py --output dist/humanities-book-plugin
python3 scripts/validate_plugin.py dist/humanities-book-plugin

자세한 지원 범위와 안전 규칙은 각 스킬의 SKILL.md를 따릅니다.

라이선스와 고지

이 프로젝트의 배포 조건은 LICENSE이며, 포함된 upstream 코드의 저작권 고지는 NOTICE에 보존합니다.