gitifact 0.7.0 → 0.8.0

package/dist/i18n/ko/changelog.md

@@ -1,3 +1,38 @@
+## 0.8.0 - 2026-09-25
+### Added
+- 프로젝트 지침: 아키텍처 규칙·검증 절차처럼 여러 기능에 걸친 일하는 방식을 `.gitifact/instructions/<이름>/`에 지침으로 두고, AGENTS.md 색인이 어떤 작업에 어느 지침을 읽을지 알립니다. 브라우저의 프로젝트 지침 화면에서 AGENTS.md와 지침, 지침 폴더의 파일을 읽습니다.
+- 결정기록: 기존 문서를 바꾸거나 여러 안 중 하나를 고르면 에이전트가 `records new`로 맥락·결정·검토한 대안을 `.gitifact/records/`에 남기고 문서와 함께 커밋합니다. 브라우저의 결정기록 화면에서 커밋·기록별로 읽고, `records list --doc <ID>`로 한 문서의 결정 흐름을 봅니다.
+- 문서 목록이 grep으로 알 수 없는 것을 골라 줍니다. `specs list`는 `--uncovered`(어떤 설계도 다루지 않는 요구사항), `--without-design`, `--draft`, `--changed-since <날짜|커밋>`, `--author`, `--q`로 거르고, 모든 목록은 `--fields`로 필요한 열만, `--format json`으로도 줍니다.
+- `feedback`: Gitifact의 버그나 개선을 말하면 에이전트가 초안을 보여 주고 확인받은 뒤 Gitifact 저장소에 이슈로 보냅니다. GitHub CLI(`gh`)가 없으면 내용을 채운 이슈 작성 페이지 주소를 알려 줍니다.
+- 브라우저 대시보드가 프로젝트 규모와 최신 결정기록을 보이고, 커밋 페이지가 문서 변경을 git 형식 비교로, 커밋이 바꾼 소스 파일과 함께 보입니다.
+- `guide show migrate`가 0.7 프로젝트를 새 문서 형식으로 옮기는 절차를 안내하고, `update`가 0.7 프로젝트에 전환이 필요하다고 알립니다.
+- 작업을 마치고 커밋하지 않은 채 다음 작업으로 넘어가면 에이전트가 커밋을 한 번 제안합니다.
+### Changed
+- 문서 형식(저장 규약 schemaVersion 3): 문서 하나가 파일 하나입니다. 기능 폴더에 `index.md`·`requirements/`·`design/`을 두고 ID·제목·관계는 프론트매터에 둡니다. 에이전트가 파일을 직접 고치고 `check`로 확인합니다. 0.7로 기록한 프로젝트는 `guide show migrate`로 한 번 옮겨야 합니다.
+- 명령을 리소스별로 정리했습니다: `specs`·`instructions`·`records`의 `list`·`show`·`new`, 전체 검사 `check`, 커밋 `changes list`·`commit`, 작성 지침 `guide list`·`show`.
+- 에이전트는 블록에 적힌 버전의 전역 `gitifact`를 씁니다. 명령이 없거나 버전이 다르면 설치를 제안하고, 그전에는 같은 버전의 npx로 실행합니다.
+- 브라우저의 제품 개요는 대시보드, 활동은 결정기록이 됐고 옛 주소(`/product`·`/activity`)는 없어졌습니다. 문서 목록과 본문의 글꼴을 Pretendard로 맞췄습니다.
+- 이력 색인을 작업 폴더의 `.gitifact/cache/index.db`에 둡니다. 커밋에서 빠지며 지워도 다시 만들어집니다.
+### Removed
+- 위키(`.gitifact/wiki/`): 프로젝트 지침으로 대신합니다. 남은 위키 페이지는 `check`가 알립니다.
+- `spec working`·`save`·`read`·`diff`·`changes`·`commit`, `docs <topic>`, `status`: 문서를 직접 고치는 방식과 `specs`·`changes`·`guide` 명령으로 대신합니다.
+- 변경 이유 파일 `history.jsonl`: 결정기록으로 대신합니다. 0.7 커밋의 이유는 이력에서 계속 읽습니다.
+- Tryce 시절 형식(`.tryce` 경로, `tryce-*` 마커, schemaVersion 1)과 이를 옮기던 `migrate` 명령.
+### Fixed
+- 브라우저의 좁은 화면에서 좌우 여백이 화면마다 달랐고, 필터와 기능 목록이 한 줄로 밀려 잘리던 문제를 고쳤습니다.
+- 한 커밋에서 여러 문서를 설명한 0.7 변경 이유가 결정기록 목록에 문서마다 되풀이되던 문제를 고쳤습니다.
+
+## 0.7.1 - 2026-09-21
+### Added
+- 에이전트가 새 세션에서 업데이트를 확인하고 사용자 동의 후 지침을 갱신하도록 안내합니다. 직접 확인할 때는 파일을 바꾸지 않는 `update --check`를 사용할 수 있습니다.
+### Changed
+- 전역 설치 없이 npx로 시작하도록 안내합니다. 에이전트 지침은 실행 버전을 고정하고, README와 시작하기의 일상 명령은 `npx gitifact`로 간단히 표시합니다.
+### Removed
+- 브라우저의 업데이트 알림과 서버의 새 버전 조회를 제거했습니다. 현재 버전과 패치노트는 계속 확인할 수 있습니다. `browser --no-update-check` 옵션도 제거했습니다.
+### Fixed
+- 병합된 작업이 머지 담당자의 활동으로 표시되던 문제를 고쳤습니다. 원본 작성자와 변경 이유를 유지하고 단순 병합의 중복 집계를 제외합니다. 병합 중 추가로 수정한 기록은 병합 커밋에 남깁니다. 기존 이력 색인은 자동으로 다시 생성됩니다.
+- 페이지 이동 버튼이 있는 긴 기능별 요구사항 목록에서 스크롤하면 프로젝트명·검색·새로고침 헤더가 사라지던 문제를 고쳤습니다.
+
 ## 0.7.0 - 2026-09-20
 ### Added
 - 사이드바 하단의 GitHub 링크로 제품 저장소를 새 탭에서 열 수 있습니다.
@@ -7,168 +42,168 @@
 - 저장소와 npm README의 기본 언어를 영어로 바꾸고 한국어 문서 링크를 제공합니다.
 - 기존 에이전트 지침 블록은 `--lang`을 지정하지 않으면 업데이트 후에도 원래 언어를 유지합니다. 프로젝트 문서·ID·이력과 schemaVersion 2 저장 규약은 그대로입니다.
 
-## 0.6.2 - 2026-09-20
-### Added
-- 기능별 요구사항 목록이 기능 아래에 그 기능의 요구사항을 한 줄씩 보여 줍니다. 누르면 상세의 그 요구사항으로 바로 이동하고 주소가 그 위치를 가리켜, 링크를 공유하거나 북마크해 두면 다시 그 자리에서 열립니다. 목록은 기능 단위로 페이지를 나누어 한 기능의 요구사항이 페이지에 걸쳐 끊기지 않습니다.
-- 요구사항에서 그 요구사항을 설명하는 설계 절로 이동할 수 있습니다. 설계가 절마다 관련 요구사항을 보여 주던 것의 반대 방향입니다.
-### Changed
-- 활동 화면의 한 항목이 커밋 하나가 됐습니다. 변경 이유는 그 이유로 바뀐 기록들 위에 한 번만 적습니다. 한 커밋이 여러 기록을 건드리면 같은 이유가 기록마다 되풀이되던 것을 없앴고, 이유를 한 줄로 자르지 않습니다. 날짜가 바뀌는 자리에는 날짜를 표시합니다.
-- 제품 개요의 "최근 변경 이력"이 "최신 활동"이 되고 활동 화면과 같은 타임라인으로 보입니다. 커밋마다 기록 10개까지 보인 뒤 나머지는 활동으로 잇습니다.
-- 다른 화면에서 특정 요구사항이나 설계 절로 들어오면 그 절의 제목에 형광펜 표시가 남아 어느 것을 보러 왔는지 알 수 있습니다. 절 옆의 세로 줄을 대신합니다.
-- 기능별 요구사항 목록의 정렬이 별도 선택 상자에서 표의 열 머리로 옮겨졌습니다. 기능 이름·요구사항 수·최근 변경 열을 눌러 정렬하고 한 번 더 누르면 방향이 바뀝니다.
-- 왼쪽 메뉴의 로고와 바닥의 버전이 메뉴 항목과 같은 선에서 시작합니다.
-### Fixed
-- 요구사항이나 설계 절을 가리키는 주소를 직접 열었을 때 그 위치로 이동하지 않던 문제를 고쳤습니다.
-- 제품 개요가 이력을 세는 동안 "전체 활동 0건"과 "커밋된 명세 활동이 아직 없습니다"를 보이던 문제를 고쳤습니다. 답이 오기 전에는 불러오는 중임을 보입니다.
-
-## 0.6.1 - 2026-09-19
-### Added
-- 브라우저가 이력을 로컬 색인(`.git/gitifact/index.sqlite`)에 둡니다. 한 번 읽은 커밋은 브라우저를 다시 띄워도 다시 읽지 않고 새 커밋만 더합니다. 작업 폴더와 `git status`에는 나타나지 않으며, 지우거나 손상돼도 다시 만들어집니다.
-- 검색창(`Ctrl`/`Cmd`+`K`)이 지난 변경도 찾습니다. 변경의 제목과 이유로 찾고, 고르면 활동 화면의 그 변경을 엽니다.
-### Changed
-- 활동의 필터와 검색어가 불러온 범위가 아니라 전체 이력에 적용됩니다. 아직 불러오지 않은 오래된 변경도 찾고, 목록 아래에 "전체 N건 중 M건"을 알립니다. 한 번에 변경 50건씩 불러옵니다.
-- 제품 개요의 변경 종류 차트와 21일 막대가 전체 이력을 셉니다. 최근 변경 이력은 커밋마다 기록을 12개까지 보이고 나머지는 "외 N건"으로 활동에 잇습니다.
-- 참여자 상세의 최근 활동이 불러온 범위와 무관하게 그 사람의 최근 변경 10건을 보입니다.
-- 활동의 변경 내용은 항목을 열 때 받아 옵니다. 목록에 없는 변경을 가리키는 링크도 그 변경을 엽니다.
-- 활동 목록을 여러 번 더 불러온 뒤 다른 화면에 다녀와도 빠르게 다시 그립니다. 334건 기준 약 2.9초에서 0.4초로 줄었고, 더보기는 불러온 양과 관계없이 일정합니다.
-- 라이트 모드의 글자와 로고를 한 단계 밝게 하고 로고를 줄였습니다. 제품 개요의 두 차트 카드는 높이가 같습니다.
-- 참여자 아바타를 손으로 그린 얼굴 그림으로 바꿨습니다.
-### Fixed
-- 스톤 외의 색 조합에서 문서의 mermaid 다이어그램이 그려지지 않던 문제를 고쳤습니다.
-- 위키 화면의 로딩 골격이 모양 없이 그려지던 문제를 고쳤습니다. 트리·경로·본문 배치대로 보입니다.
-- 검색창에 입력하는 동안 "검색할 문서가 없습니다" 안내가 깜빡이던 문제를 고쳤습니다. 결과를 기다리는 동안에는 결과 줄 모양의 골격이 보입니다.
-
-## 0.6.0 - 2026-09-19
-### Added
-- 브라우저가 문서의 ```mermaid 코드 펜스를 다이어그램으로, `> [!NOTE]` 같은 GitHub 알림을 종류가 드러나는 상자로 그립니다. 그리는 코드는 패키지에 함께 담아 외부 서비스를 부르지 않습니다.
-- 브라우저에 문서 검색을 추가했습니다. `Ctrl`(macOS는 `Cmd`)+`K`나 모든 화면 머리의 검색 버튼으로 열고, 기능 명세·요구사항·설계·위키 페이지를 제목과 본문으로 함께 찾아 분류별로 보여 줍니다. 고르면 그 문서가 있는 화면으로 이동합니다.
-- 기능별 요구사항 목록을 설계 여부·참여자로 좁히고 최근 변경순·요구사항 많은 순·이름순으로 정렬할 수 있습니다. 고른 조건은 주소에 남아 기능을 열고 돌아와도 유지됩니다.
-- `gitifact docs writing`을 추가했습니다. 위키 페이지·요구사항·설계에 공통으로 적용하는 문체, 인용과 Alert·다이어그램을 쓰는 기준, AI가 쓴 문장에서 흔한 상투구를 덜어내는 기준을 담습니다. `docs spec`·`docs design`·`docs wiki`가 이 문서를 가리킵니다.
-### Changed
-- 제품 개요가 최근 변경 이력을 본문으로 보여 줍니다. 요약 타일 다섯 개 대신 프로젝트 규모 한 줄과 차트 두 장을 위에 두고, 그 아래에 커밋별 변경 이유와 그 커밋이 건드린 기록을 싣습니다.
-- 브라우저가 불러온 이력을 화면을 옮겨도 유지합니다. 이전에는 다른 메뉴에 다녀올 때마다 불러온 페이지를 전부 다시 읽었습니다. 현재 명세·위키·참여자는 첫 페이지에만 실어 "더 보기"가 같은 내용을 다시 보내지 않습니다.
-- 검색창은 타자가 멈춘 뒤 500ms에 검색합니다. 활동·기능·참여자 화면의 검색창과 문서 검색이 같은 값을 씁니다.
-- 기능 목록의 표에서 모든 행이 같은 값을 갖던 설계 열을 빼고 설계가 없는 기능만 제목 옆에 표시합니다. 요구사항 수에는 가장 많은 기능 대비 막대를 함께 그리고, 모든 행의 높이를 같게 맞췄습니다.
-- GITIFACT 블록의 명령 목록에 `docs writing`이 들어가고, 문서를 쓰기 전에 그 문체를 따르라는 규칙이 늘었습니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
-### Removed
-- deprecated였던 `spec prepare`·`spec verify`·`spec commit-plan`·`spec commit-apply`를 삭제했습니다. 0.5.0에서 예고한 일정입니다. 이유 기록과 커밋은 `spec commit` 하나로 합니다.
-
-## 0.5.1 - 2026-09-18
-### Changed
-- `init`이 새 버전이 있는지 확인해 결과의 `update`·`install`에 알립니다. 이미 설치된 이전 버전으로 도입해도 새 버전이 있다는 것을 알 수 있습니다. 확인에 실패해도 초기화는 진행되며 `GITIFACT_NO_UPDATE_CHECK`로 끌 수 있습니다. `init` 출력 계약이 version 5가 되었습니다.
-- 소개 글의 시작 프롬프트가 이미 설치돼 있어도 `npm install -g gitifact@latest`로 최신 버전을 설치하도록 안내합니다.
-- CLI보다 새로운 저장 규약을 쓰는 프로젝트에서는 CLI를 최신 버전으로 올리라고 안내합니다.
-### Fixed
-- 0.4.x로 `init`한 프로젝트에서 0.5.0이 새로 `init`하라고 안내하면서 `init`도 거부해 진행할 수 없던 문제를 고쳤습니다. `.gitifact`에 설정 파일만 있으면 `init`이 새 저장 규약으로 바꾸고 결과에 `replaced`로 표시합니다. 이전 규약의 명세나 기록이 있으면 바꾸지 않고 해야 할 일을 안내합니다.
-
-## 0.5.0 - 2026-09-18
-### Added
-- 프로젝트 위키를 추가했습니다. 기능에 묶이지 않는 제품 설명·구조·규칙을 `.gitifact/wiki/`에 하위 폴더로 자유롭게 두고, 페이지마다 CLI가 발급한 W-ID로 추적합니다. `spec save`의 `create-doc`·`update-doc`·`move-doc`·`delete-doc`으로 저장하고 커밋할 때 변경 이유를 붙입니다.
-- 위키의 `README.md`가 위키 운영 방침입니다. `init`이 처음 도입할 때 아키텍처 결정 기록(ADR)을 쌓는 기본 방침으로 만들고, 고치면 `docs wiki`가 그 내용을 이 프로젝트의 방침으로 보여 줍니다.
-- 이미지·PDF 같은 파일을 `.gitifact/assets/`에 두고 문서에서 상대 경로로 참조할 수 있습니다. `spec working`이 대상 없는 링크, 큰 파일, 권장하지 않는 확장자, 어떤 문서도 참조하지 않는 에셋을 경고합니다.
-- 설계 문서의 frontmatter `sources`에 참고 문서를 적으면 브라우저 설계 탭 위에 목록으로 보입니다.
-- 브라우저에 프로젝트 위키 메뉴를 추가했습니다. 왼쪽 트리와 오른쪽의 폴더 내용 또는 페이지로 된 탐색기입니다.
-- 브라우저가 문서 본문의 상대 링크를 해당 위키 페이지·기능·에셋으로 연결합니다. `.gitifact` 밖의 저장소 파일은 열지 않고 경로를 복사합니다.
-- `init`이 AGENTS.md에 블록을 쓸 때 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄로 된 CLAUDE.md를 만들어 Claude Code도 블록을 읽게 합니다. `update`는 파일을 만들지 않고 없다는 사실만 알립니다.
-### Changed
-- 저장 규약이 schemaVersion 2가 되었습니다. 파일 ID는 frontmatter에 둡니다. 0.4.x로 만든 프로젝트(schemaVersion 1)는 이 버전에서 읽지 않으며 전환 도구도 없습니다. CLI가 이유를 알리고, 새로 `init`해야 합니다.
-- 브라우저가 제품 개요에서 시작합니다. 활동은 `/activity`로 옮겼고, 필터나 선택이 담긴 이전 활동 주소는 같은 조건의 활동 페이지로 이어집니다.
-- 브라우저의 요구사항 메뉴 이름을 기능별 요구사항으로 바꿨습니다.
-- GITIFACT 블록이 요구사항·설계·코드를 바꾸기 전에 `docs wiki`를 확인하고, 위키 운영 방식을 바꾸려면 위키 README를 고치도록 안내합니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
-- 명세 지침의 예시에서 제목 뒤의 "요구사항"을 뺐습니다. 명세 제목은 기능 이름만 씁니다.
-- `update` 출력 계약이 version 3이 되었습니다. `agentDocs.missing`에 없는 CLAUDE.md를 알립니다.
-### Removed
-- 제품 문서와 지침 폴더, 브라우저의 지침 메뉴를 없앴습니다. 같은 내용은 프로젝트 위키에 둡니다.
-### Fixed
-- 브라우저 검색창에서 한글이 조합 도중 끊기거나 "ㄱ거검검"처럼 겹쳐 입력되던 문제를 고쳤습니다.
-
-## 0.4.4 - 2026-09-17
-### Added
-- `update --commit`이 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋합니다. 다른 staging은 그대로 남고 훅·서명도 평소대로 실행됩니다. 블록 밖에도 수정이 있거나, 추적하지 않는 파일이거나, Git이 커밋을 거부하면 커밋하지 않고 이유를 알립니다.
-- GITIFACT 블록이 `gitifact` 명령이 없는 환경을 안내합니다. 에이전트는 사용자에게 알리고 동의를 받아 블록에 적힌 버전으로 설치합니다.
-### Changed
-- GITIFACT 블록을 `## Gitifact Guide` 제목, 절 제목, 목록으로 정리하고 끝에 구분선을 넣었습니다. Markdown으로 볼 때 명령 목록이 한 줄로 합쳐지지 않습니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
-- 브라우저의 업데이트 안내 문장이 설치 후 `gitifact update --commit`을 실행하도록 안내합니다.
-- `update` 출력 계약이 version 2가 되었습니다. 커밋 결과를 담는 `commit` 필드가 추가됐습니다.
-
-## 0.4.3 - 2026-09-17
-### Fixed
-- 브라우저의 새 버전 안내 창에서 제목과 닫기 버튼이 창 가장자리에 붙어 잘려 보이던 문제를 고쳤습니다.
-- 같은 창에서 복사 버튼이 요청 문장과 겹치던 문제를 고쳤습니다. 복사 버튼은 각 코드 블록의 제목 줄에 표시됩니다.
-
-## 0.4.2 - 2026-09-17
-### Added
-- `spec working`과 `spec changes`가 저장·커밋 입력 파일을 둘 경로(`inputs.save`·`inputs.commit`)를 알려 줍니다. 기본은 운영체제 임시 폴더이고, 그곳에 쓸 수 없는 환경에서는 Git이 무시하는 `.gitifact/tmp/`를 씁니다.
-- 알려 준 경로의 입력으로 `spec save`·`spec commit`이 성공하면 CLI가 입력 파일을 지우고 결과에 `inputRemoved`를 표시합니다. 실패·`--dry-run`·결과가 불확실한 커밋에서는 남깁니다. 이 폴더의 7일 넘은 파일은 조회 때 정리됩니다.
-- `spec save`·`spec commit`이 `--file -`로 표준 입력을 받습니다.
-- `spec working`에 `--stamp`(stamp와 입력 경로만), `--feature <폴더>`(한 기능만), `--ids`(ID·제목·경로만) 옵션을 추가했습니다.
-### Changed
-- GITIFACT 블록과 작업 흐름 문서가 입력 파일을 알려 준 경로에 쓰고 조회 결과를 파일로 남기지 않도록 안내합니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
-- 사용자가 요구사항·프로젝트 현황·변경 이력을 보여 달라고 하면 에이전트가 `browser`를 백그라운드로 실행해 URL을 알려 주도록 안내합니다.
-
-## 0.4.1 - 2026-09-17
-### Added
-- 브라우저에 설정 페이지를 추가했습니다. 화면 모드(시스템·라이트·다크)와 색 조합 다섯 가지(스톤, 세이지 & 크림, 올리브 & 웜그레이, 슬레이트 & 블루, 샌드 & 클레이)를 고를 수 있고, 선택은 그 브라우저에만 저장됩니다.
-- 제품 개요에서 제품 문서를 별도의 읽기 페이지로 엽니다.
-### Changed
-- 제품 문서·지침·요구사항·설계·소개 문서를 더 읽기 좋게 다듬었습니다. 본문을 16px로 키우고 문단·코드·표를 같은 폭에 맞췄으며 제목 크기와 간격, 표·인용·링크 모양을 정리했습니다.
-- 코드 블록에 구문 색을 입혔습니다. 기존에는 색이 모두 회색이라 구분되지 않았습니다.
-- 지침 열 보기에서 폴더 행에 문서 수를 표시해 문서 행과 높이를 맞췄습니다.
-- 활동 상세의 변경 내용 박스를 위아래 선만 남겨 단순화했습니다.
-- 사이드 메뉴 하단에는 버전만 표시합니다.
-### Fixed
-- 활동 상세를 스크롤할 때 고정된 제목 위로 본문이 겹쳐 보이던 문제를 고쳤습니다.
-
-## 0.4.0 - 2026-09-17
-### Added
-- 브라우저가 새 버전을 알려 줍니다. 에이전트에게 전달할 업데이트 요청 문장과 npm 전역 설치용 명령을 복사할 수 있습니다. 설치는 자동으로 실행하지 않습니다.
-- 브라우저 사이드 메뉴 하단에 실행 중인 CLI 버전을 표시합니다.
-- 브라우저에 패치노트 페이지를 추가했습니다. 버전별 추가·변경·제거·수정 내역을 최신순으로 보여 줍니다.
-- `update` 명령이 새 버전 여부와 설치 방법을 알려 주고, 프로젝트 지침 파일의 GITIFACT 블록을 현재 버전으로 갱신합니다.
-- `browser --no-update-check` 옵션과 `GITIFACT_NO_UPDATE_CHECK` 환경변수로 새 버전 확인을 끌 수 있습니다.
-### Changed
-- `browser`를 시작할 때 CLI가 npm 레지스트리(registry.npmjs.org)에 최신 버전을 한 번 조회합니다. 프로젝트 정보는 보내지 않으며, 실패해도 브라우저는 그대로 동작합니다.
-- `browser-session` 계약이 version 2가 되어 `cliVersion`과 `update` 필드를 포함합니다.
-- GITIFACT 블록의 명령 목록에 `update`를 추가했습니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
-
-## 0.3.2 - 2026-09-17
-### Added
-- 버전별 변경 내역을 패치노트로 함께 배포합니다.
-- `spec changes`·`spec working`·`spec save`·`spec read`·`spec diff` 도움말에 명령 설명을 추가했습니다.
-- 브라우저 소개 페이지에 로고를 보여 주고 소개 글을 새로 정리했습니다.
-### Changed
-- GITIFACT 블록 첫 줄에 언어(`ko`)를 표시합니다. `init`을 다시 실행하면 갱신되며, 이전 형식의 블록도 그대로 읽습니다.
-### Fixed
-- CLI 안내가 구형 JSON 프로젝트용으로 존재하지 않는 `gitifact@0.4.0`을 안내하던 것을 `@tryce/cli@0.4.0`으로 바로잡았습니다.
-
-## 0.3.1 - 2026-09-17
-### Added
-- 브라우저에 제품 개요 대시보드와 Gitifact 소개 페이지를 추가했습니다.
-- 지침 문서를 열 보기로 훑고 미리보기로 읽을 수 있습니다.
-- 헤더에 마지막 조회 시각을, Git 상태 메뉴에 미커밋 변경 표시를 보여 줍니다.
-### Changed
-- 요구사항 메뉴의 이름과 순서를 정리했습니다.
-
-## 0.3.0 - 2026-09-16
-### Added
-- `init`이 AGENTS.md·CLAUDE.md·`.cursorrules` 등 에이전트 지침 파일에 `GITIFACT:START`/`GITIFACT:END` 블록을 쓰고, 다시 실행하면 그 사이만 갱신합니다.
-- `init`에 `--agent`·`--remove-agents`·`--skip-agents` 옵션을 추가했습니다.
-- `docs <topic>` 명령이 번들된 지침 문서 다섯 편(workflow·spec·design·product·commit)을 출력합니다.
-### Changed
-- `project-init` 계약이 version 4가 됐습니다.
-### Removed
-- `skills install`·`skills sync`·`skills remove` 명령과 배포 스킬 파일을 제거했습니다. 0.2.0 스킬 설치본은 자동으로 정리하지 않으므로, 설치한 스킬 파일을 직접 삭제하고 `init`을 다시 실행하세요.
-
-## 0.2.0 - 2026-09-15
-### Added
-- 1920px 이상 화면에서 브라우저의 기본 글자 크기를 키웁니다.
-### Changed
-- 브라우저의 기여자 화면을 참여자 화면으로 바꿨습니다.
-- 기능·참여자 상세를 `/features/<S-ID>`·`/contributors/<이메일>` 경로로 옮겼습니다. 이전 `?feature=`·`?author=` 링크는 리다이렉트하지 않습니다.
-- Git 상태 페이지를 다른 페이지와 같은 구조로 정리했습니다.
-
-## 0.1.0 - 2026-09-15
-### Added
-- `migrate` 명령으로 이전 `@tryce/cli` 저장소를 Gitifact 형식으로 전환합니다. 과거 커밋 기록은 그대로 읽힙니다.
-### Changed
-- Tryce에서 Gitifact로 이름을 바꿨습니다. 패키지는 `gitifact`, 실행 명령은 `gitifact`, 저장 경로는 `.gitifact`, 스킬은 `gitifact-workflow`입니다.
+## 0.6.2 - 2026-09-20
+### Added
+- 기능별 요구사항 목록이 기능 아래에 그 기능의 요구사항을 한 줄씩 보여 줍니다. 누르면 상세의 그 요구사항으로 바로 이동하고 주소가 그 위치를 가리켜, 링크를 공유하거나 북마크해 두면 다시 그 자리에서 열립니다. 목록은 기능 단위로 페이지를 나누어 한 기능의 요구사항이 페이지에 걸쳐 끊기지 않습니다.
+- 요구사항에서 그 요구사항을 설명하는 설계 절로 이동할 수 있습니다. 설계가 절마다 관련 요구사항을 보여 주던 것의 반대 방향입니다.
+### Changed
+- 활동 화면의 한 항목이 커밋 하나가 됐습니다. 변경 이유는 그 이유로 바뀐 기록들 위에 한 번만 적습니다. 한 커밋이 여러 기록을 건드리면 같은 이유가 기록마다 되풀이되던 것을 없앴고, 이유를 한 줄로 자르지 않습니다. 날짜가 바뀌는 자리에는 날짜를 표시합니다.
+- 제품 개요의 "최근 변경 이력"이 "최신 활동"이 되고 활동 화면과 같은 타임라인으로 보입니다. 커밋마다 기록 10개까지 보인 뒤 나머지는 활동으로 잇습니다.
+- 다른 화면에서 특정 요구사항이나 설계 절로 들어오면 그 절의 제목에 형광펜 표시가 남아 어느 것을 보러 왔는지 알 수 있습니다. 절 옆의 세로 줄을 대신합니다.
+- 기능별 요구사항 목록의 정렬이 별도 선택 상자에서 표의 열 머리로 옮겨졌습니다. 기능 이름·요구사항 수·최근 변경 열을 눌러 정렬하고 한 번 더 누르면 방향이 바뀝니다.
+- 왼쪽 메뉴의 로고와 바닥의 버전이 메뉴 항목과 같은 선에서 시작합니다.
+### Fixed
+- 요구사항이나 설계 절을 가리키는 주소를 직접 열었을 때 그 위치로 이동하지 않던 문제를 고쳤습니다.
+- 제품 개요가 이력을 세는 동안 "전체 활동 0건"과 "커밋된 명세 활동이 아직 없습니다"를 보이던 문제를 고쳤습니다. 답이 오기 전에는 불러오는 중임을 보입니다.
+
+## 0.6.1 - 2026-09-19
+### Added
+- 브라우저가 이력을 로컬 색인(`.git/gitifact/index.sqlite`)에 둡니다. 한 번 읽은 커밋은 브라우저를 다시 띄워도 다시 읽지 않고 새 커밋만 더합니다. 작업 폴더와 `git status`에는 나타나지 않으며, 지우거나 손상돼도 다시 만들어집니다.
+- 검색창(`Ctrl`/`Cmd`+`K`)이 지난 변경도 찾습니다. 변경의 제목과 이유로 찾고, 고르면 활동 화면의 그 변경을 엽니다.
+### Changed
+- 활동의 필터와 검색어가 불러온 범위가 아니라 전체 이력에 적용됩니다. 아직 불러오지 않은 오래된 변경도 찾고, 목록 아래에 "전체 N건 중 M건"을 알립니다. 한 번에 변경 50건씩 불러옵니다.
+- 제품 개요의 변경 종류 차트와 21일 막대가 전체 이력을 셉니다. 최근 변경 이력은 커밋마다 기록을 12개까지 보이고 나머지는 "외 N건"으로 활동에 잇습니다.
+- 참여자 상세의 최근 활동이 불러온 범위와 무관하게 그 사람의 최근 변경 10건을 보입니다.
+- 활동의 변경 내용은 항목을 열 때 받아 옵니다. 목록에 없는 변경을 가리키는 링크도 그 변경을 엽니다.
+- 활동 목록을 여러 번 더 불러온 뒤 다른 화면에 다녀와도 빠르게 다시 그립니다. 334건 기준 약 2.9초에서 0.4초로 줄었고, 더보기는 불러온 양과 관계없이 일정합니다.
+- 라이트 모드의 글자와 로고를 한 단계 밝게 하고 로고를 줄였습니다. 제품 개요의 두 차트 카드는 높이가 같습니다.
+- 참여자 아바타를 손으로 그린 얼굴 그림으로 바꿨습니다.
+### Fixed
+- 스톤 외의 색 조합에서 문서의 mermaid 다이어그램이 그려지지 않던 문제를 고쳤습니다.
+- 위키 화면의 로딩 골격이 모양 없이 그려지던 문제를 고쳤습니다. 트리·경로·본문 배치대로 보입니다.
+- 검색창에 입력하는 동안 "검색할 문서가 없습니다" 안내가 깜빡이던 문제를 고쳤습니다. 결과를 기다리는 동안에는 결과 줄 모양의 골격이 보입니다.
+
+## 0.6.0 - 2026-09-19
+### Added
+- 브라우저가 문서의 ```mermaid 코드 펜스를 다이어그램으로, `> [!NOTE]` 같은 GitHub 알림을 종류가 드러나는 상자로 그립니다. 그리는 코드는 패키지에 함께 담아 외부 서비스를 부르지 않습니다.
+- 브라우저에 문서 검색을 추가했습니다. `Ctrl`(macOS는 `Cmd`)+`K`나 모든 화면 머리의 검색 버튼으로 열고, 기능 명세·요구사항·설계·위키 페이지를 제목과 본문으로 함께 찾아 분류별로 보여 줍니다. 고르면 그 문서가 있는 화면으로 이동합니다.
+- 기능별 요구사항 목록을 설계 여부·참여자로 좁히고 최근 변경순·요구사항 많은 순·이름순으로 정렬할 수 있습니다. 고른 조건은 주소에 남아 기능을 열고 돌아와도 유지됩니다.
+- `gitifact docs writing`을 추가했습니다. 위키 페이지·요구사항·설계에 공통으로 적용하는 문체, 인용과 Alert·다이어그램을 쓰는 기준, AI가 쓴 문장에서 흔한 상투구를 덜어내는 기준을 담습니다. `docs spec`·`docs design`·`docs wiki`가 이 문서를 가리킵니다.
+### Changed
+- 제품 개요가 최근 변경 이력을 본문으로 보여 줍니다. 요약 타일 다섯 개 대신 프로젝트 규모 한 줄과 차트 두 장을 위에 두고, 그 아래에 커밋별 변경 이유와 그 커밋이 건드린 기록을 싣습니다.
+- 브라우저가 불러온 이력을 화면을 옮겨도 유지합니다. 이전에는 다른 메뉴에 다녀올 때마다 불러온 페이지를 전부 다시 읽었습니다. 현재 명세·위키·참여자는 첫 페이지에만 실어 "더 보기"가 같은 내용을 다시 보내지 않습니다.
+- 검색창은 타자가 멈춘 뒤 500ms에 검색합니다. 활동·기능·참여자 화면의 검색창과 문서 검색이 같은 값을 씁니다.
+- 기능 목록의 표에서 모든 행이 같은 값을 갖던 설계 열을 빼고 설계가 없는 기능만 제목 옆에 표시합니다. 요구사항 수에는 가장 많은 기능 대비 막대를 함께 그리고, 모든 행의 높이를 같게 맞췄습니다.
+- GITIFACT 블록의 명령 목록에 `docs writing`이 들어가고, 문서를 쓰기 전에 그 문체를 따르라는 규칙이 늘었습니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
+### Removed
+- deprecated였던 `spec prepare`·`spec verify`·`spec commit-plan`·`spec commit-apply`를 삭제했습니다. 0.5.0에서 예고한 일정입니다. 이유 기록과 커밋은 `spec commit` 하나로 합니다.
+
+## 0.5.1 - 2026-09-18
+### Changed
+- `init`이 새 버전이 있는지 확인해 결과의 `update`·`install`에 알립니다. 이미 설치된 이전 버전으로 도입해도 새 버전이 있다는 것을 알 수 있습니다. 확인에 실패해도 초기화는 진행되며 `GITIFACT_NO_UPDATE_CHECK`로 끌 수 있습니다. `init` 출력 계약이 version 5가 되었습니다.
+- 소개 글의 시작 프롬프트가 이미 설치돼 있어도 `npm install -g gitifact@latest`로 최신 버전을 설치하도록 안내합니다.
+- CLI보다 새로운 저장 규약을 쓰는 프로젝트에서는 CLI를 최신 버전으로 올리라고 안내합니다.
+### Fixed
+- 0.4.x로 `init`한 프로젝트에서 0.5.0이 새로 `init`하라고 안내하면서 `init`도 거부해 진행할 수 없던 문제를 고쳤습니다. `.gitifact`에 설정 파일만 있으면 `init`이 새 저장 규약으로 바꾸고 결과에 `replaced`로 표시합니다. 이전 규약의 명세나 기록이 있으면 바꾸지 않고 해야 할 일을 안내합니다.
+
+## 0.5.0 - 2026-09-18
+### Added
+- 프로젝트 위키를 추가했습니다. 기능에 묶이지 않는 제품 설명·구조·규칙을 `.gitifact/wiki/`에 하위 폴더로 자유롭게 두고, 페이지마다 CLI가 발급한 W-ID로 추적합니다. `spec save`의 `create-doc`·`update-doc`·`move-doc`·`delete-doc`으로 저장하고 커밋할 때 변경 이유를 붙입니다.
+- 위키의 `README.md`가 위키 운영 방침입니다. `init`이 처음 도입할 때 아키텍처 결정 기록(ADR)을 쌓는 기본 방침으로 만들고, 고치면 `docs wiki`가 그 내용을 이 프로젝트의 방침으로 보여 줍니다.
+- 이미지·PDF 같은 파일을 `.gitifact/assets/`에 두고 문서에서 상대 경로로 참조할 수 있습니다. `spec working`이 대상 없는 링크, 큰 파일, 권장하지 않는 확장자, 어떤 문서도 참조하지 않는 에셋을 경고합니다.
+- 설계 문서의 frontmatter `sources`에 참고 문서를 적으면 브라우저 설계 탭 위에 목록으로 보입니다.
+- 브라우저에 프로젝트 위키 메뉴를 추가했습니다. 왼쪽 트리와 오른쪽의 폴더 내용 또는 페이지로 된 탐색기입니다.
+- 브라우저가 문서 본문의 상대 링크를 해당 위키 페이지·기능·에셋으로 연결합니다. `.gitifact` 밖의 저장소 파일은 열지 않고 경로를 복사합니다.
+- `init`이 AGENTS.md에 블록을 쓸 때 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄로 된 CLAUDE.md를 만들어 Claude Code도 블록을 읽게 합니다. `update`는 파일을 만들지 않고 없다는 사실만 알립니다.
+### Changed
+- 저장 규약이 schemaVersion 2가 되었습니다. 파일 ID는 frontmatter에 둡니다. 0.4.x로 만든 프로젝트(schemaVersion 1)는 이 버전에서 읽지 않으며 전환 도구도 없습니다. CLI가 이유를 알리고, 새로 `init`해야 합니다.
+- 브라우저가 제품 개요에서 시작합니다. 활동은 `/activity`로 옮겼고, 필터나 선택이 담긴 이전 활동 주소는 같은 조건의 활동 페이지로 이어집니다.
+- 브라우저의 요구사항 메뉴 이름을 기능별 요구사항으로 바꿨습니다.
+- GITIFACT 블록이 요구사항·설계·코드를 바꾸기 전에 `docs wiki`를 확인하고, 위키 운영 방식을 바꾸려면 위키 README를 고치도록 안내합니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
+- 명세 지침의 예시에서 제목 뒤의 "요구사항"을 뺐습니다. 명세 제목은 기능 이름만 씁니다.
+- `update` 출력 계약이 version 3이 되었습니다. `agentDocs.missing`에 없는 CLAUDE.md를 알립니다.
+### Removed
+- 제품 문서와 지침 폴더, 브라우저의 지침 메뉴를 없앴습니다. 같은 내용은 프로젝트 위키에 둡니다.
+### Fixed
+- 브라우저 검색창에서 한글이 조합 도중 끊기거나 "ㄱ거검검"처럼 겹쳐 입력되던 문제를 고쳤습니다.
+
+## 0.4.4 - 2026-09-17
+### Added
+- `update --commit`이 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋합니다. 다른 staging은 그대로 남고 훅·서명도 평소대로 실행됩니다. 블록 밖에도 수정이 있거나, 추적하지 않는 파일이거나, Git이 커밋을 거부하면 커밋하지 않고 이유를 알립니다.
+- GITIFACT 블록이 `gitifact` 명령이 없는 환경을 안내합니다. 에이전트는 사용자에게 알리고 동의를 받아 블록에 적힌 버전으로 설치합니다.
+### Changed
+- GITIFACT 블록을 `## Gitifact Guide` 제목, 절 제목, 목록으로 정리하고 끝에 구분선을 넣었습니다. Markdown으로 볼 때 명령 목록이 한 줄로 합쳐지지 않습니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
+- 브라우저의 업데이트 안내 문장이 설치 후 `gitifact update --commit`을 실행하도록 안내합니다.
+- `update` 출력 계약이 version 2가 되었습니다. 커밋 결과를 담는 `commit` 필드가 추가됐습니다.
+
+## 0.4.3 - 2026-09-17
+### Fixed
+- 브라우저의 새 버전 안내 창에서 제목과 닫기 버튼이 창 가장자리에 붙어 잘려 보이던 문제를 고쳤습니다.
+- 같은 창에서 복사 버튼이 요청 문장과 겹치던 문제를 고쳤습니다. 복사 버튼은 각 코드 블록의 제목 줄에 표시됩니다.
+
+## 0.4.2 - 2026-09-17
+### Added
+- `spec working`과 `spec changes`가 저장·커밋 입력 파일을 둘 경로(`inputs.save`·`inputs.commit`)를 알려 줍니다. 기본은 운영체제 임시 폴더이고, 그곳에 쓸 수 없는 환경에서는 Git이 무시하는 `.gitifact/tmp/`를 씁니다.
+- 알려 준 경로의 입력으로 `spec save`·`spec commit`이 성공하면 CLI가 입력 파일을 지우고 결과에 `inputRemoved`를 표시합니다. 실패·`--dry-run`·결과가 불확실한 커밋에서는 남깁니다. 이 폴더의 7일 넘은 파일은 조회 때 정리됩니다.
+- `spec save`·`spec commit`이 `--file -`로 표준 입력을 받습니다.
+- `spec working`에 `--stamp`(stamp와 입력 경로만), `--feature <폴더>`(한 기능만), `--ids`(ID·제목·경로만) 옵션을 추가했습니다.
+### Changed
+- GITIFACT 블록과 작업 흐름 문서가 입력 파일을 알려 준 경로에 쓰고 조회 결과를 파일로 남기지 않도록 안내합니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
+- 사용자가 요구사항·프로젝트 현황·변경 이력을 보여 달라고 하면 에이전트가 `browser`를 백그라운드로 실행해 URL을 알려 주도록 안내합니다.
+
+## 0.4.1 - 2026-09-17
+### Added
+- 브라우저에 설정 페이지를 추가했습니다. 화면 모드(시스템·라이트·다크)와 색 조합 다섯 가지(스톤, 세이지 & 크림, 올리브 & 웜그레이, 슬레이트 & 블루, 샌드 & 클레이)를 고를 수 있고, 선택은 그 브라우저에만 저장됩니다.
+- 제품 개요에서 제품 문서를 별도의 읽기 페이지로 엽니다.
+### Changed
+- 제품 문서·지침·요구사항·설계·소개 문서를 더 읽기 좋게 다듬었습니다. 본문을 16px로 키우고 문단·코드·표를 같은 폭에 맞췄으며 제목 크기와 간격, 표·인용·링크 모양을 정리했습니다.
+- 코드 블록에 구문 색을 입혔습니다. 기존에는 색이 모두 회색이라 구분되지 않았습니다.
+- 지침 열 보기에서 폴더 행에 문서 수를 표시해 문서 행과 높이를 맞췄습니다.
+- 활동 상세의 변경 내용 박스를 위아래 선만 남겨 단순화했습니다.
+- 사이드 메뉴 하단에는 버전만 표시합니다.
+### Fixed
+- 활동 상세를 스크롤할 때 고정된 제목 위로 본문이 겹쳐 보이던 문제를 고쳤습니다.
+
+## 0.4.0 - 2026-09-17
+### Added
+- 브라우저가 새 버전을 알려 줍니다. 에이전트에게 전달할 업데이트 요청 문장과 npm 전역 설치용 명령을 복사할 수 있습니다. 설치는 자동으로 실행하지 않습니다.
+- 브라우저 사이드 메뉴 하단에 실행 중인 CLI 버전을 표시합니다.
+- 브라우저에 패치노트 페이지를 추가했습니다. 버전별 추가·변경·제거·수정 내역을 최신순으로 보여 줍니다.
+- `update` 명령이 새 버전 여부와 설치 방법을 알려 주고, 프로젝트 지침 파일의 GITIFACT 블록을 현재 버전으로 갱신합니다.
+- `browser --no-update-check` 옵션과 `GITIFACT_NO_UPDATE_CHECK` 환경변수로 새 버전 확인을 끌 수 있습니다.
+### Changed
+- `browser`를 시작할 때 CLI가 npm 레지스트리(registry.npmjs.org)에 최신 버전을 한 번 조회합니다. 프로젝트 정보는 보내지 않으며, 실패해도 브라우저는 그대로 동작합니다.
+- `browser-session` 계약이 version 2가 되어 `cliVersion`과 `update` 필드를 포함합니다.
+- GITIFACT 블록의 명령 목록에 `update`를 추가했습니다. `update` 또는 `init`을 다시 실행하면 갱신됩니다.
+
+## 0.3.2 - 2026-09-17
+### Added
+- 버전별 변경 내역을 패치노트로 함께 배포합니다.
+- `spec changes`·`spec working`·`spec save`·`spec read`·`spec diff` 도움말에 명령 설명을 추가했습니다.
+- 브라우저 소개 페이지에 로고를 보여 주고 소개 글을 새로 정리했습니다.
+### Changed
+- GITIFACT 블록 첫 줄에 언어(`ko`)를 표시합니다. `init`을 다시 실행하면 갱신되며, 이전 형식의 블록도 그대로 읽습니다.
+### Fixed
+- CLI 안내가 구형 JSON 프로젝트용으로 존재하지 않는 `gitifact@0.4.0`을 안내하던 것을 `@tryce/cli@0.4.0`으로 바로잡았습니다.
+
+## 0.3.1 - 2026-09-17
+### Added
+- 브라우저에 제품 개요 대시보드와 Gitifact 소개 페이지를 추가했습니다.
+- 지침 문서를 열 보기로 훑고 미리보기로 읽을 수 있습니다.
+- 헤더에 마지막 조회 시각을, Git 상태 메뉴에 미커밋 변경 표시를 보여 줍니다.
+### Changed
+- 요구사항 메뉴의 이름과 순서를 정리했습니다.
+
+## 0.3.0 - 2026-09-16
+### Added
+- `init`이 AGENTS.md·CLAUDE.md·`.cursorrules` 등 에이전트 지침 파일에 `GITIFACT:START`/`GITIFACT:END` 블록을 쓰고, 다시 실행하면 그 사이만 갱신합니다.
+- `init`에 `--agent`·`--remove-agents`·`--skip-agents` 옵션을 추가했습니다.
+- `docs <topic>` 명령이 번들된 지침 문서 다섯 편(workflow·spec·design·product·commit)을 출력합니다.
+### Changed
+- `project-init` 계약이 version 4가 됐습니다.
+### Removed
+- `skills install`·`skills sync`·`skills remove` 명령과 배포 스킬 파일을 제거했습니다. 0.2.0 스킬 설치본은 자동으로 정리하지 않으므로, 설치한 스킬 파일을 직접 삭제하고 `init`을 다시 실행하세요.
+
+## 0.2.0 - 2026-09-15
+### Added
+- 1920px 이상 화면에서 브라우저의 기본 글자 크기를 키웁니다.
+### Changed
+- 브라우저의 기여자 화면을 참여자 화면으로 바꿨습니다.
+- 기능·참여자 상세를 `/features/<S-ID>`·`/contributors/<이메일>` 경로로 옮겼습니다. 이전 `?feature=`·`?author=` 링크는 리다이렉트하지 않습니다.
+- Git 상태 페이지를 다른 페이지와 같은 구조로 정리했습니다.
+
+## 0.1.0 - 2026-09-15
+### Added
+- `migrate` 명령으로 이전 `@tryce/cli` 저장소를 Gitifact 형식으로 전환합니다. 과거 커밋 기록은 그대로 읽힙니다.
+### Changed
+- Tryce에서 Gitifact로 이름을 바꿨습니다. 패키지는 `gitifact`, 실행 명령은 `gitifact`, 저장 경로는 `.gitifact`, 스킬은 `gitifact-workflow`입니다.

package/dist/i18n/ko/docs/commit.md

@@ -1,45 +1,46 @@
-# 커밋 시점의 최종 변경
+---
+title: 커밋 시점의 최종 변경
+description: 커밋 입력, 결정기록과 함께 커밋하기, 나눠 커밋하기, 실패 후 복구
+---
 
 자동 기록은 커밋 권한이 아니다. 사용자 커밋 요청 또는 명시적 프로젝트 정책이 있을 때 실행한다. 정책이 없다는 이유로 자동 커밋하지 않으며 이미 부여된 권한은 다시 묻지 않는다. 푸시는 별도 권한을 따른다.
 
 ## 절차
 
-1. 실제 diff와 관련 테스트를 확인한다. 필요하면 `spec changes`로 HEAD 대비 최종 명세 차이와 pendingReasons를 읽는다.
-2. 아래 입력을 `spec working` 또는 `spec changes` 결과의 `inputs.commit` 경로에 UTF-8 JSON으로 쓰고 `spec commit --file <그 경로>`를 실행한다. 커밋이 성공하면 CLI가 입력 파일을 지운다. 범위나 이유 누락을 먼저 보려면 `--dry-run`을 붙인다. dry-run은 파일을 쓰거나 커밋하지 않는다.
-3. 성공 결과와 실제 Git 상태를 확인하고, 반환된 withoutReason이 있으면 이유 누락으로 보고한다.
+1. 실제 diff와 관련 테스트를 확인하고 `gitifact changes list`를 실행한다. HEAD 대비 바뀐 문서, 커밋하지 않은 결정기록과 각 기록이 설명하는 문서, 결정기록이 없는 수정·이동·삭제, 문서 검사 결과, 커밋 입력 파일 경로가 나온다.
+2. 아래 입력을 그 경로에 UTF-8 JSON으로 쓰고 `gitifact changes commit --file <그 경로>`를 실행한다. 범위나 기록 누락을 먼저 보려면 `--dry-run`을 붙인다. dry-run은 파일을 쓰거나 커밋하지 않는다. 커밋이 성공하면 CLI가 입력 파일을 지운다.
+3. 성공 결과와 실제 Git 상태를 확인한다. 결과의 `withoutRecord`에 문서가 남아 있으면 결정기록 누락으로 보고한다.
 
 ```json
 {
-  "reasons": [{ "requirements": ["실제 R-ID"], "reason": "대화·결정에서 확인한 변경 이유" }],
-  "paths": [".gitifact/spec/posts/requirements.md", ".gitifact/spec/posts/history.jsonl", "src/posts.ts", "test/posts.test.ts"],
+  "paths": [".gitifact/records/20260924/DR-실제값.md", ".gitifact/spec/posts/requirements/delete.md", ".gitifact/spec/posts/design/overview.md", "src/posts.ts", "test/posts.test.ts"],
   "message": "프로젝트 정책에 맞는 메시지",
   "authorization": { "basis": "user-request", "evidence": "실제 커밋 요청과 작업 범위" }
 }
 ```
 
-basis는 user-request 또는 project-policy다. 예시 경로와 근거를 그대로 복사하지 않는다. 추가 정책은 policyFiles, 코드만 커밋할 때의 연결은 requirements 배열에 실제 R-ID로 전달한다. changes를 보고 이유를 썼다면 그 expected를 함께 넘겨 그사이의 명세 변경을 거부할 수 있다. CLI는 자연어 권한의 진위를 판정하지 않는다.
+예시 경로·ID·근거를 그대로 복사하지 않는다. 입력에는 이 세 필드만 둔다. `basis`는 `user-request` 또는 `project-policy`다. CLI는 자연어 권한의 진위를 판정하지 않는다.
 
 ## 입력 규칙
 
-- reasons는 이번에 남길 **전체 미커밋 이유 목록**이므로 여전히 유효한 pendingReasons도 포함한다. 생략하면 이미 준비된 미커밋 이유를 그대로 유지한다. 모르는 이유는 꾸며내지 않는다. 이유가 없어도 커밋은 진행되며 withoutReason으로 표시된다.
-- 위키 페이지의 변경 이유는 `{requirements: [], documents: [실제 W-ID], reason: 실제 이유}`로 전달한다. 이유는 `.gitifact/wiki/history.jsonl`에 기록되므로 바뀐 페이지와 그 파일을 paths에 포함한다.
-- 설계 변경 이유는 `{requirements: [], designs: [실제 S-ID], reason: 실제 이유}`로 전달한다. 요구사항과 같은 이유이면 두 배열을 함께 지정한다. 변경된 design.md와 history.jsonl을 paths에 포함한다. 설계만 바뀌면 요구사항 변경이나 완료를 만들지 않는다.
-- paths에는 변경한 명세와 그 history.jsonl, 관련 코드·테스트를 담는다. 문서가 참조하는 새 에셋(`.gitifact/assets/…`)도 함께 담는다. 명세 이동이면 양쪽 명세를 포함한다. 기록할 이유가 없는 history.jsonl은 건너뛴다. 미커밋 명세·이유 전체가 선택돼야 하므로 서로 무관한 작업이 섞였다면 강제 포함하지 않고 제한을 알린다.
-- 실행 전에는 staging하지 않는다. 기존 staging이나 intent-to-add가 있으면 보존하고 보류한다.
-- 수정 후 원복돼 최종 차이가 없으면 새 이유도 없다. 커밋된 history.jsonl을 덮어쓰지 않는다.
-- history에는 이유와 요구사항·설계·페이지 연결만 두며 원문 before/after·작성자·시각을 복제하지 않는다. 과거 명세는 `spec read --ref`, 변경은 `spec diff --from --to`로 Git 커밋에서 읽는다. Git 작성자를 사용자 요청·승인의 증거로 취급하지 않는다.
-- 훅 등으로 커밋이 거부되고 HEAD가 그대로면 이번에 쓴 이유 파일과 index는 실행 전으로 돌아간다. 원인을 고친 뒤 같은 입력으로 다시 실행한다. 실패 후 훅·서명을 끄지 않는다. HEAD가 바뀐 불확실한 실행은 재시도하지 않고 복구 자료를 확인한다. 잠금이나 index 백업을 임의 삭제하거나 커밋을 reset하지 않는다.
+- **결정기록:** 기록은 결정한 순간에 `gitifact records new`로 만들어 둔 파일이다(`gitifact guide show records`). 커밋할 기록 파일을 `paths`에 넣는다. 넣지 않은 기록은 작업 폴더에 남아 다음 커밋을 기다린다. 커밋하는 기록에 `draft: true`가 남아 있으면 거부된다.
+- **기록이 필요한 변경:** 기존 문서를 바꾸거나 옮기거나 지웠는데 그 문서를 가리키는 기록이 없으면 `withoutRecord`로 표시된다. 커밋을 막지는 않는다. 새로 만든 문서는 기록이 없어도 된다. 모르는 이유를 꾸며내지 않는다.
+- **`paths`:** 이번 커밋에 담을 문서 파일, 결정기록 파일, 관련 코드·테스트를 담는다. 바뀐 문서를 모두 담을 필요는 없다. 담지 않은 문서는 다음 커밋으로 남는다. 옮긴 문서는 옛 경로와 새 경로를 함께 담아야 한다. 지운 문서는 지운 경로를 담는다. 문서가 참조하는 새 에셋(`.gitifact/assets/…`)도 함께 담는다.
+- **커밋된 기록:** 이미 커밋된 기록을 고치거나 지우면 `changes list`와 `check`가 알리고 `changes commit`이 거부한다. HEAD대로 되돌리고 바뀐 결정은 새 기록으로 쓴다.
+- **검사:** 커밋 직전에 `check`와 같은 검사를 돌린다. 문제가 있거나 문서·커밋할 기록에 `draft: true`가 남아 있으면 커밋하지 않는다. 링크·에셋 경고는 커밋을 막지 않는다.
+- **staging:** 실행 전에 staging하지 않는다. 기존 staging이나 intent-to-add가 있으면 CLI가 거부한다. 스스로 만든 staging(`git mv`·`git rm` 등)은 `git restore --staged`로 풀고 파일은 그대로 둔 채 다시 실행한다. 파일을 지우거나 옮길 때는 `git rm`·`git mv` 대신 일반 삭제·이동을 쓴다.
+- **실패 후:** 훅 등으로 커밋이 거부되고 HEAD가 그대로면 index는 실행 전으로 돌아가고 파일은 그대로다. 원인을 고친 뒤 같은 입력으로 다시 실행한다. 실패 후 훅·서명을 끄지 않는다. 결과를 확인하지 못했다는 오류(HEAD가 바뀌었을 수 있음)면 재시도하지 않고 안내된 복구 자료와 HEAD를 확인한다. 잠금 폴더나 index 백업을 임의로 지우거나 커밋을 reset하지 않는다.
 
 커밋 참조는 구현 완료 선언이 아니다. 실제 테스트 결과와 남은 제한을 별도로 알린다.
 
 ## 무엇을 한 커밋에 담는가
 
-기본은 관련 명세·이유·소스·테스트를 같은 커밋에 담는 것이다. 분리 정책이면 명세와 이유를 먼저 커밋하고 코드·테스트 커밋에서 실제 R-ID를 참조한다. 기존 사용자 변경이나 staging을 지우거나 무관한 변경까지 포함하지 않는다.
+기본은 결정 하나를 커밋 하나에 담는 것이다. 그 결정기록, 결정이 바꾼 문서, 그것을 구현한 코드·테스트를 함께 담는다. `changes list`는 기록마다 설명하는 문서를 보여 주므로 이것을 보고 나눈다. 두 기록이 한 문서를 함께 설명하면(`두 기록이 함께 설명하는 문서`) 그 기록들은 한 커밋에 담는다. 코드 파일은 CLI가 기록에 나눠 주지 못하므로 어느 결정의 것인지 판단해 담고, 한 파일이 두 결정에 걸치면 함께 담는다.
 
-## 메시지
+작업 하나를 마치고 커밋하지 않은 채 다음 작업을 시작하게 되면 커밋을 한 번 제안한다. 다음 작업이 같은 파일을 고치면 두 결정이 한 파일에 섞여 결정별로 나눠 커밋하기 어렵고, 이력에서 어느 변경이 어느 결정의 것인지 흐려진다는 점을 한 줄로 알린다. 제안은 커밋 권한이 아니므로 사용자가 답하기 전에 커밋하지 않고, 원하지 않으면 같은 세션에서 다시 묻지 않는다.
 
-프로젝트의 커밋 메시지 규약을 따른다. 규약이 없으면 첫 줄에 무엇을 바꿨는지, 본문에 왜 바꿨는지를 짧게 쓴다. 요구사항·설계·페이지 연결 트레일러는 CLI가 붙이므로 메시지에 직접 쓰지 않는다.
+프로젝트에 커밋을 묶는 규칙이 있으면 그 규칙을 따른다. 분리 정책이면 문서와 기록을 먼저 커밋하고, 이어지는 코드·테스트 커밋의 메시지에서 관련 문서를 설명한다. 기존 사용자 변경이나 staging을 지우거나 무관한 변경까지 포함하지 않는다.
 
-## 이유 쓰기
+## 메시지와 트레일러
 
-이유는 대화와 결정에서 확인한 사실만 적는다. 기각한 대안이 이후 작업에 영향을 주면 함께 적는다. 커밋 참조를 구현 완료로 보고하지 않고, 실제 실행한 검증과 남은 제한을 따로 알린다.
+프로젝트의 커밋 메시지 규약을 따른다. 규약이 없으면 첫 줄에 무엇을 바꿨는지, 본문에 왜 바꿨는지를 짧게 쓴다. CLI가 바뀐 문서와 기록이 가리킨 문서로 트레일러를 붙인다(요구사항은 `Gitifact-Req`, 설계는 `Gitifact-Design`, 기능·지침은 `Gitifact-Doc`, 결정기록은 `Gitifact-Record`). 메시지에 `Gitifact-`로 시작하는 줄을 직접 쓰면 거부된다.

package/dist/i18n/ko/docs/design.md

@@ -1,52 +1,71 @@
-# 기능 설계 형식
+---
+title: 기능 설계 형식
+description: 설계 축과 파일 나누기, 프론트매터, 다이어그램, 개정 방식
+---
+
+설계는 기능 폴더의 `design/` 아래 파일들이며, 그 기능의 요구사항을 구현하는 구조와 처리 방식을 설명한다. 파일 하나가 설계의 한 관점(축)을 맡는다.
+
+## 축과 파일 나누기
+
+| 파일 | 다루는 것 |
+| :--- | :--- |
+| `overview.md` (필수) | 범위와 접근 방식, 구성 요소와 경계, 미결 사항 |
+| `data.md` | 저장 형식, 데이터 구조와 관계, 캐시, 상태와 수명 |
+| `interface.md` | 명령·API·계약, 입력과 출력, 다른 모듈과의 경계 |
+| `ui.md` | 화면 구성과 경로, 표시 흐름, 상호작용 |
+| `errors.md` | 오류 처리, 입력 검증, 복구, 검사 범위 |
+
+설계가 하나라도 있으면 `overview.md`가 있어야 한다. 나머지 축은 권장이며, 필요한 축만 만든다. 기능이 작아 각 관점이 한두 문단이면 `overview.md` 하나로 둔다. 한 관점이 여러 절 분량이 되거나 다른 관점과 따로 고쳐지면 그 축의 파일로 옮긴다. 빈 축 파일이나 양식만 채운 파일을 만들지 않는다. 표에 없는 관점이 필요하면 소문자·숫자·하이픈 slug로 파일을 더 둘 수 있다.
 
-설계는 기능 폴더의 `design.md` 하나이며 여러 요구사항을 구현하는 공통 구조와 처리 방식을 설명한다.
+같은 내용을 두 파일에 적지 않는다. `overview.md`는 다른 축의 세부를 요약해 반복하지 않고, 어떤 축 파일이 있는지 읽는 사람이 알 수 있으면 충분하다.
 
 ## 파일 구조
 
-frontmatter의 `id`는 소유 명세의 S-ID이며 CLI가 쓴다. 설계가 참고한 문서는 frontmatter의 `sources` 목록에 둔다. 항목마다 `title`과 `path`(위키 페이지로 가는 이 파일 기준 상대 경로, `.md`) 또는 `url`(http/https) 중 하나, 선택적 `note`를 쓴다. 본문 곳곳에 흩어진 링크 대신 이 목록으로 참고 문서를 관리하고, 브라우저는 이 목록을 설계 탭에 카드로 보여 준다. 외부 페이지의 제목이나 미리보기는 가져오지 않는다.
+파일은 `gitifact specs new design <기능>/<축> --title "<제목>" --description "<한 줄>"`로 만든다. CLI가 D- ID를 발급하고 `order`를 같은 폴더의 최댓값+10으로 매기며 `draft: true`를 붙인다. 본문을 채운 뒤 `draft: true` 줄을 지우고 `gitifact check`로 확인한다. ID를 직접 만들지 않는다.
 
 ```markdown
 ---
-id: S-소유명세의실제값
+id: D-CLI가발급한값
+title: 게시물 저장 구조
+description: 게시물과 첨부 파일의 저장 형식과 삭제 시 정리 순서
+order: 20
+requirements:
+  - R-관련요구사항의실제값
 sources:
-  - title: 아키텍처
-    path: ../../wiki/architecture.md
+  - id: I-따른지침의실제값
     note: 계층 구조와 의존 방향
   - title: 라이브러리 문서
     url: https://example.test/docs
 ---
 
-# 게시물 관리 설계
-
-## 개요
-구현할 범위와 접근 방식.
-
-## 처리 흐름
-<!-- gitifact-ref: R-관련요구사항의실제값 -->
-입력부터 결과까지의 핵심 흐름.
+게시물은 ...
 ```
 
-위 문장은 구조 설명이다. 실제 저장할 때는 파악한 내용으로 채우고 예시 ID와 안내 문장을 그대로 저장하지 않는다. 절 단위 참조는 실제 ID로 `<!-- gitifact-ref: R-ID, R-ID -->`를 쓴다. 코드 블록의 예시는 참조가 아니다. 본문의 상대 링크(`../../assets/flow.png` 등)는 브라우저가 해당 대상으로 연결한다.
+위 ID와 문장은 구조 설명이다. 실제 값으로 채우고 예시를 그대로 저장하지 않는다.
 
-본문의 문체는 `gitifact docs writing`을 따른다. 다이어그램과 Alert도 그 문서의 기준대로 쓴다.
+- **`title`·`description`:** 필수이며 한 줄이다. 제목은 본문에 `#`로 다시 쓰지 않는다. 본문 절은 `##`부터 쓰고 gitifact 주석을 넣지 않는다.
+- **`order`:** 기능을 이해하기 좋은 순서로 매긴다. overview가 맨 앞이고 기본은 data → interface → ui → errors 순이다. 같은 폴더에서 겹치면 안 된다.
+- **`requirements`:** 이 파일이 실제로 설명하는 요구사항의 R- ID만 적는다. 한 요구사항을 여러 설계 파일이 가리켜도 된다. 기능 전체의 요구사항을 모든 파일에 복사하지 않는다.
+- **`sources`:** 이 파일이 근거로 삼은 문서다. 저장소 안의 문서는 `{id, note?}`로 ID만, 외부 자료는 `{title, url, note?}`로 적는다. 브라우저는 이 목록을 참고 문서 카드로 보여 준다. 외부 페이지의 제목이나 미리보기는 가져오지 않는다.
 
-## 저장과 참조
+본문의 상대 링크(`../../../assets/flow.png` 등)는 이 파일 기준 경로로 쓰며 브라우저가 해당 대상으로 연결한다. 문서 사이의 관계는 링크가 아니라 프론트매터로 나타낸다.
 
-`spec save`의 operations에 `set-design`(type·feature·title·body·선택적 sources 배열)을 사용한다. create·add·set-design을 같은 요청에 담아 두 파일을 저장할 수 있다. CLI가 frontmatter를 작성하며 빈 설계를 자동 생성하지 않는다. 신규 R-ID는 반환된 결과에서 얻은 뒤 참조가 필요한 설계 절을 후속 save로 보완한다. ID를 미리 만들어 넣지 않는다. 설계 삭제는 `delete-design`(type·feature)이다.
+## 본문 작성
 
-working/save의 `MISSING_DESIGN_REFERENCE` 경고는 삭제·이동 여부와 원문을 확인하고 필요하면 수정한다. `MISSING_LINK_TARGET`은 sources의 path나 본문 링크 대상이 없을 때 나온다. 경고를 무시한 채 연결이 유효하다고 주장하지 않는다.
+본문의 문체는 `gitifact guide show writing`을 따른다. 본문에는 지금의 구조와 동작을 쓴다. 확정한 것, 구현에서 관측한 것, 제안을 구분한다.
 
-## 언제 쓰는가
+설계는 결정 표를 두지 않는다. 여러 안 중 하나를 고른 결정은 그 맥락과 검토한 대안과 함께 결정기록으로 남기고 본문에는 고른 결과만 규칙으로 쓴다(`gitifact guide show records`). 설계를 고치기 전에 `gitifact records list --doc <D-ID>`로 그 설계의 결정 흐름을 읽어, 이미 고르지 않은 안을 다시 제안하지 않는다. 바뀐 경위·날짜·옛 방식도 본문이 아니라 기록에 둔다.
 
-새 기능을 정리할 때 requirements.md와 design.md를 함께 작성하는 것이 기본이다. 사용자가 요구사항만 요청하면 따르고, 기존 명세에 설계가 없다고 일괄 생성하지 않는다. 설계는 형식상 선택이며 단계별 승인을 강제하지 않는다. 중요한 불명확함만 질문한다. tasks.md는 아직 다루지 않는다.
+다이어그램은 종류 고르기와 작성 규칙을 `gitifact guide show writing`에서 따르고, 그림이 설명하는 축의 파일에 둔다. 축마다 잘 맞는 종류가 있다. data는 `erDiagram`과 캐시·읽기 흐름의 `flowchart`, interface는 구성 요소 사이 요청의 `sequenceDiagram`, ui는 화면 상태의 `stateDiagram-v2`, errors는 실패와 복구 흐름에 쓴다.
 
-## 목차
+설계를 쓰기 전에 AGENTS.md 색인에서 작업 영역의 지침을 읽고, 따른 지침은 `sources`에 올린다. 지침에 있는 내용은 설계에 다시 쓰지 않는다. 설계에는 이 기능에만 해당하는 것만 쓴다. 지침은 설계를 가리키지 않으므로 관계는 이 한 방향으로만 적는다. 설계가 지침의 기준과 어긋나면 지침을 먼저 고칠지 사용자와 정한다.
 
-다음 목차를 기본으로 하되 필요한 절만 쓴다: 개요 / 구조와 데이터 / 처리 흐름 / 오류 처리와 검증 / 주요 설계 결정 / 미결 사항. 확정·관측·제안을 구분하고 중요한 대안과 선택 이유를 덧붙인다. 결정 목록만으로 구현 설명을 대신하지 않는다. 미결 사항이 없으면 그 절을 생략한다.
+## 언제 쓰는가
 
-설계를 쓰기 전에 위키의 구조·규칙 페이지를 읽고, 따른 페이지는 `sources`에 올린다. 설계가 위키의 기준과 어긋나면 문서를 먼저 고칠지 사용자와 정한다.
+새 기능을 정리할 때 요구사항과 설계를 함께 쓰는 것이 기본이다. 사용자가 요구사항만 요청하면 따르고, 설계가 없는 기존 기능에 일괄로 만들지 않는다. 단계별 승인을 강제하지 않으며 중요한 불명확함만 질문한다.
 
 ## 개정
 
-개정 전 기존 설계와 관련 요구사항을 읽고 영향을 받는 절을 수정한다. 매번 전체 문서를 재작성하지 않고 현재 유효한 설계를 유지한다. 과거 원문은 Git이 보존한다. 요구사항을 바꾸면 설계도 검토하고, 설계만 바뀌면 요구사항을 억지로 수정하지 않는다.
+개정 전에 그 기능의 설계 파일들과 관련 요구사항을 읽고 영향을 받는 파일만 고친다. 바뀐 문장은 고쳐 쓰고 '전에는 …했다'는 문장을 덧붙이지 않는다. 바뀐 경위는 결정기록에 쓰고 과거 원문은 Git이 보존한다. 결정이 바뀌면 본문의 규칙을 고치고 새 결정기록을 쓴다. 요구사항을 바꾸면 그것을 가리키는 설계도 검토하고(`gitifact specs show <R-ID>`의 "가리키는 문서"), 설계만 바뀌면 요구사항을 억지로 고치지 않는다.
+
+한 파일이 커져 축을 나누거나 합칠 때는 문장을 옮기기만 하고 같은 커밋에서 내용을 고치지 않는다. 옮긴 뒤 옛 파일의 문장이 새 파일들에 빠짐없이 있는지 대조한다. 파일을 옮겨도 ID는 그대로 두고, 지운 파일의 `requirements`가 남은 파일로 옮겨졌는지 확인한다. 옮기기만 한 커밋에는 결정기록을 쓰지 않아도 된다.