From e333c3d41d19f469f35b3c77da125b8e9aa2e502 Mon Sep 17 00:00:00 2001 From: YONGBEOM GWON Date: Tue, 25 Aug 2026 15:44:12 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=84=A4=EA=B3=84=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=EB=A5=BC=20docs/=20=EB=A3=A8=ED=8A=B8=EB=A1=9C=20=EC=9D=B4?= =?UTF-8?q?=EB=8F=99=ED=95=98=EA=B3=A0=20=EC=97=AD=EC=82=AC=EC=A0=81=20?= =?UTF-8?q?=EA=B3=84=ED=9A=8D=EC=84=9C=20=EB=B3=B8=EB=AC=B8=EC=9D=84=20?= =?UTF-8?q?=EB=B3=B5=EC=9B=90=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/superpowers/ 는 개발 도구 어휘가 경로에 남은 것이었다. 코드와 문서가 이 경로를 참조하는 곳이 세 군데(CLAUDE.md · 개발계획서 · check_licenses.py) 있어 함께 갱신한다. spec 은 바이트 동일 순수 리네임(R100), plan 은 3~4행(에이전트 도구 지시문)만 제거하고 8,225행 본문을 복원(R99). 제출한 개발계획서가 "63개 태스크 완료"를 주장하며 이 문서의 Task 63개·Phase 3개를 근거로 드는데, 11줄 스텁을 커밋하면 그 근거가 저장소에서 사라진다. plan 상단에 문서 지위 노트를 추가했다. 381개 미체크 항목이 현재 미완료 표시가 아니라 TDD 절차 템플릿임을 밝히고, 계획 시점과 현재 코드의 결정 차이(Anthropic→Ollama 기본, Kanana 교체, spaCy·dateparser·korean-number 미탑재)를 선제 설명한다. CLAUDE.md 가 plan 을 "spec 6.8이 가리키는 문서"로 지목하고 있었는데 이는 원래부터 틀렸다 — spec 6.8(임계 & 라우팅)은 spec 254행에 있지 plan 에는 없다. spec 을 정본으로, plan 을 실행 계획으로 각각 가리키도록 정정했다. check_licenses.py 의 시크릿 스캔 제외 경로도 새 이름으로 맞췄다. 틀린 채 본문을 복원하면 플레이스홀더 AWS 키·PEM·주민번호 패턴이 3건 오탐으로 CI 를 깬다. .gitignore 에 _workspace/ 와 *.bak-* 를 추가해 git add -A 지뢰를 제거했다. --- .gitignore | 6 ++++++ CLAUDE.md | 3 ++- ...md => 2026-06-30-ttobak-easy-read-engine-spec.md} | 0 ...0-ttobak-mvp.md => 2026-06-30-ttobak-mvp-plan.md} | 12 +++++++++++- ...\232\215\354\204\234-\353\230\220\353\260\225.md" | 2 +- tooling/check_licenses.py | 2 +- 6 files changed, 21 insertions(+), 4 deletions(-) rename docs/{superpowers/specs/2026-06-30-ttobak-easy-read-engine-design.md => 2026-06-30-ttobak-easy-read-engine-spec.md} (100%) rename docs/{superpowers/plans/2026-06-30-ttobak-mvp.md => 2026-06-30-ttobak-mvp-plan.md} (99%) diff --git a/.gitignore b/.gitignore index 622429d..1f8bf34 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,9 @@ docs/contest/ot-2026/ # 내부 영업·접촉 문서 (공개 산출물 아님) PILOT-OUTREACH.md + +# 로컬 리뷰·실행 스크래치 (공개 산출물 아님) +_workspace/ + +# 편집 중 생긴 백업본 — 진짜 안전망은 git 히스토리다 +*.bak-* diff --git a/CLAUDE.md b/CLAUDE.md index 4cbe01b..9d1ce44 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co **또박(Ttobak)** — 어려운 한국어 공공·행정 문서를 "쉬운 정보(Easy-Read)"로 변환하는 오픈소스 엔진. 쉬움을 K-ER 점수로 측정하고, Fidelity 게이트로 사실(숫자·날짜·금액·기한·자격·기관명)을 보존하며 자가 교정한다. 2026 오픈소스 개발자대회 출품작. 코드 Apache-2.0 / 데이터(corpus) CC BY 4.0 / 픽토그램(assets) CC BY-SA — 세 라이선스는 절대 섞이면 안 된다(아래 라이선스 절 참조). -상세 스펙은 `docs/superpowers/plans/2026-06-30-ttobak-mvp.md` — 코드 docstring의 "spec 6.8" 같은 인용이 가리키는 문서다. +상세 스펙은 `docs/2026-06-30-ttobak-easy-read-engine-spec.md` — 코드 docstring의 "spec 6.8" 같은 인용이 가리키는 문서다. +구현 계획(63개 TDD 태스크)은 `docs/2026-06-30-ttobak-mvp-plan.md`(역사적 계획서, 상단 지위 노트 참조). ## 명령어 diff --git a/docs/superpowers/specs/2026-06-30-ttobak-easy-read-engine-design.md b/docs/2026-06-30-ttobak-easy-read-engine-spec.md similarity index 100% rename from docs/superpowers/specs/2026-06-30-ttobak-easy-read-engine-design.md rename to docs/2026-06-30-ttobak-easy-read-engine-spec.md diff --git a/docs/superpowers/plans/2026-06-30-ttobak-mvp.md b/docs/2026-06-30-ttobak-mvp-plan.md similarity index 99% rename from docs/superpowers/plans/2026-06-30-ttobak-mvp.md rename to docs/2026-06-30-ttobak-mvp-plan.md index 6f8c280..6e29755 100644 --- a/docs/superpowers/plans/2026-06-30-ttobak-mvp.md +++ b/docs/2026-06-30-ttobak-mvp-plan.md @@ -1,6 +1,16 @@ # 또박(Ttobak) MVP Implementation Plan -REQUIRED SUB-SKILL: superpowers:subagent-driven-development or superpowers:executing-plans — each task below is a TDD unit (write failing test → run red → implement → run green → commit). Workers MUST follow that loop and check off each `- [ ]` step as it completes. +> **문서 지위 (2026-08-25 추가)** — 이 문서는 2026-06-30 구현 착수 전에 작성한 역사적 +> 실행 계획이다. 아래 미체크 항목(`- [ ]`)은 당시 TDD 절차 템플릿이며 **현재 미완료 표시가 +> 아니다** — 63개 태스크는 전부 완료됐고 구현 실물은 저장소 코드, 실행 이력은 git 히스토리가 +> 정본이다. +> +> 구현 뒤 바뀐 결정: LLM 프로바이더 기본값은 **Ollama 로컬(`qwen2.5:7b`)**, Anthropic 은 +> 선택적 원격 대안이다(아래 Architecture/Tech Stack 의 "Anthropic API default" 는 계획 시점 +> 표기). Kanana-1.5-8B 는 Ollama 공식 라이브러리 부재로 2026-07-29 교체(PR #3). spaCy NER · +> dateparser · korean-number 는 MVP 에 싣지 않았다(로드맵). OpenAI 프로바이더는 없다. +> 현재 동작의 정본은 `README.md`, `docs/providers.md`, `pyproject.toml` 및 코드다. +> 설계 명세는 `docs/2026-06-30-ttobak-easy-read-engine-spec.md`. **Goal:** Ship an open-source (Apache-2.0) Korean Easy-Read engine that converts hard public/administrative documents into easy-read text, measures easiness with a rule-based K-ER score, self-corrects via a generate→measure→revise loop, and preserves facts (numbers/dates/amounts/deadlines/eligibility/entities) through a deterministic fidelity gate — with a side-by-side renderer, pictogram lookup, web demo, evaluation harness, and a license/security CI gate, all by 8/27. diff --git "a/docs/contest/2026-\352\260\234\353\260\234\352\263\204\355\232\215\354\204\234-\353\230\220\353\260\225.md" "b/docs/contest/2026-\352\260\234\353\260\234\352\263\204\355\232\215\354\204\234-\353\230\220\353\260\225.md" index c0c7f64..a2420d2 100644 --- "a/docs/contest/2026-\352\260\234\353\260\234\352\263\204\355\232\215\354\204\234-\353\230\220\353\260\225.md" +++ "b/docs/contest/2026-\352\260\234\353\260\234\352\263\204\355\232\215\354\204\234-\353\230\220\353\260\225.md" @@ -280,4 +280,4 @@ CC BY-SA 픽토그램은 Apache 코드나 CC BY 데이터에 인라인·base64 --- -문서 근거 파일(저장소 기준 상대경로): 설계 명세 `docs/superpowers/specs/2026-06-30-ttobak-easy-read-engine-design.md` · MVP 계획 `docs/superpowers/plans/2026-06-30-ttobak-mvp.md` · 코어 `ttobak/` · 감사 게이트 `tooling/check_licenses.py` · 코퍼스(n=11) `corpus/pairs.jsonl` · 코퍼스 주석기 `tooling/annotate_corpus.py` · 라이선스 근거 `LICENSE` · `NOTICE` · `THIRD_PARTY_LICENSES.md` · `README.md` · `pyproject.toml`. (SDD 진행 원장 `.superpowers/sdd/progress.md`는 내부 개발 기록으로 배포본에 포함하지 않는다.) +문서 근거 파일(저장소 기준 상대경로): 설계 명세 `docs/superpowers/specs/2026-06-30-ttobak-easy-read-engine-design.md` · MVP 계획 `docs/2026-06-30-ttobak-mvp-plan.md` · 코어 `ttobak/` · 감사 게이트 `tooling/check_licenses.py` · 코퍼스(n=11) `corpus/pairs.jsonl` · 코퍼스 주석기 `tooling/annotate_corpus.py` · 라이선스 근거 `LICENSE` · `NOTICE` · `THIRD_PARTY_LICENSES.md` · `README.md` · `pyproject.toml`. (SDD 진행 원장 `.superpowers/sdd/progress.md`는 내부 개발 기록으로 배포본에 포함하지 않는다.) diff --git a/tooling/check_licenses.py b/tooling/check_licenses.py index a15472f..394e518 100644 --- a/tooling/check_licenses.py +++ b/tooling/check_licenses.py @@ -203,7 +203,7 @@ def check_assets_separation(root: Path) -> list[LicenseViolation]: # .superpowers/sdd/task-58/59/63-*.md (excluded above). NOTE: don't spell # the placeholder key out literally in this file — the regex it's meant # to demonstrate would flag this comment too (self-referential match). - "docs/superpowers/plans/2026-06-30-ttobak-mvp.md", + "docs/2026-06-30-ttobak-mvp-plan.md", }) _SCANNABLE_SUFFIXES: frozenset[str] = frozenset({