gitifact 0.7.0 → 0.8.0

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

@@ -0,0 +1,81 @@
+---
+title: 프로젝트 지침 형식
+description: 작업별 지침 폴더의 형식, AGENTS.md 색인, 명세와의 관계, 에셋과 커밋
+---
+
+프로젝트 지침은 이 프로젝트에서 어떻게 일하는지를 담는다. 아키텍처 규칙, 여러 기능에 걸친 결정, 문체, 검증 절차가 여기에 들어간다. 요구사항은 무엇을 만들지, 설계는 한 기능을 어떻게 만들지를 말하고, 지침은 기능과 무관하게 일하는 방식을 말한다. 기능별 동작은 명세에 두고 지침에 반복하지 않는다.
+
+## 폴더와 파일
+
+지침 하나는 `.gitifact/instructions/<이름>/` 폴더다. 이름은 소문자·숫자·하이픈 80자까지다. 폴더의 `index.md`가 지침 문서이고, 긴 내용은 같은 폴더의 `references/` 아래 파일로 나눈다. `index.md`는 필요한 references를 상대 링크로 가리킨다.
+
+```text
+.gitifact/instructions/
+  cli-architecture/
+    index.md                 지침 문서 (I-)
+    references/
+      checklist.md           긴 목록
+  verification/
+    index.md
+```
+
+새 지침은 CLI로 만든다. CLI가 `I-` ID를 발급하고 프론트매터를 채우며 `draft: true`를 붙인다. 본문을 채운 뒤 이 줄을 지우고 `gitifact check`로 확인한다.
+
+```text
+gitifact instructions new code-review --title "코드 리뷰" --description "리뷰에서 확인할 것과 보고 형식. 변경을 리뷰할 때 쓴다."
+```
+
+```markdown
+---
+id: I-CLI가발급한값
+title: 코드 리뷰
+description: 리뷰에서 확인할 것과 보고 형식. 변경을 리뷰할 때 쓴다.
+---
+
+규칙과 이유. 긴 목록은 [references/checklist.md](references/checklist.md)에 둔다.
+```
+
+위 ID와 문장은 구조 설명이다. `index.md`의 프론트매터는 `id`·`title`·`description`만 두고 모두 필수다. `description`에는 무엇을 담는지와 어떤 작업 때 읽는지를 함께 쓴다. 제목은 본문에 `#`로 다시 쓰지 않으며, 본문 절은 `##`부터 쓰고 gitifact 주석을 넣지 않는다. references 파일은 문서로 파싱하지 않으므로 프론트매터와 ID가 없고 형식이 자유롭다. 본문의 문체는 `gitifact guide show writing`을 따른다.
+
+이미 있는 지침은 파일을 직접 고친다. 이름을 바꿀 때는 폴더를 옮기고 ID를 유지하며, 지울 때는 폴더를 지운다. 지운 지침을 설계의 `sources`가 가리키고 있으면 그 설계도 고쳐야 `check`가 통과한다. `index.md`가 없는 지침 폴더는 `INSTRUCTION_INDEX_REQUIRED` 문제다.
+
+## AGENTS.md 색인
+
+에이전트는 모든 세션에서 AGENTS.md를 읽는다. 어떤 작업 때 어느 지침을 읽을지는 AGENTS.md의 GITIFACT 블록 밖에 짧게 적는다. 블록은 CLI가 갱신하므로 색인을 블록 안에 쓰지 않는다.
+
+```markdown
+## 작업별 지침
+
+- CLI 코드를 바꿀 때: `.gitifact/instructions/cli-architecture/index.md`
+- 변경을 검증하거나 커밋하기 전: `.gitifact/instructions/verification/index.md`
+```
+
+지침을 만들거나 이름을 바꾸거나 지우면 색인도 함께 고친다. 매 세션 필요한 짧은 사실은 AGENTS.md에 두고, 특정 작업 때만 필요한 내용은 지침에 둔다.
+
+## 명세와의 관계
+
+지침은 명세를 가리키지 않는다. 지침은 여러 기능에 걸친 지식이라, 한 기능의 명세에 묶이면 명세가 바뀔 때 함께 낡는다. 설계가 따른 지침을 `sources`에 `{id: I-…}`로 올리는 한 방향만 둔다. 지침 폴더의 Markdown이 `.gitifact/spec/` 아래를 링크하면 `INSTRUCTION_SPEC_LINK` 문제다. 저장 형식을 설명하는 경로 패턴을 코드 블록 안에 쓰는 것은 링크가 아니다.
+
+지침 사이의 링크와 에셋으로 가는 링크는 이 파일 기준 상대 경로로 쓴다. 예: `../verification/index.md`, `../../assets/diagrams/flow.png`. 대상이 없는 링크는 `check`와 `changes list`가 `MISSING_LINK_TARGET` 경고로 알린다.
+
+## 결정
+
+지침은 결정 표나 결정 기록 파일을 스스로 두지 않는다. 여러 기능에 걸친 구조·기술 선택은 지침 본문에 규칙으로 쓰고, 그 맥락과 검토한 대안은 그 지침을 가리키는 결정기록으로 남긴다(`gitifact guide show records`). 지침을 고치기 전에 `gitifact records list --doc <I-ID>`로 결정 흐름을 읽는다. 결정이 바뀌면 본문의 규칙을 고치고 새 결정기록을 쓴다.
+
+지침을 새로 만들거나 넓히면 설계들에서 같은 내용을 `gitifact specs list --q`로 찾아 지운다. 지운 설계의 `sources`에 그 지침을 더하고, 옮긴 사실을 결정기록 하나로 남긴다(`docs`에 지침과 고친 설계들).
+
+## 에셋
+
+이미지·PDF 등 Markdown이 아닌 파일은 지침 폴더 안이나 `.gitifact/assets/` 아래에 둔다. 한 지침만 쓰는 파일은 그 폴더에, 여러 문서가 함께 쓰는 파일은 assets에 둔다. assets의 권장 확장자는 png·jpg·gif·webp·svg·pdf, 권장 크기는 파일당 1MB·전체 50MB 이하다. 넘어도 커밋은 되며 `check`와 `changes list`가 `ASSET_SIZE`·`ASSET_EXTENSION`·`ASSETS_TOTAL_SIZE` 경고로 알린다. 어떤 문서도 참조하지 않는 assets 파일은 `UNREFERENCED_ASSET`으로 알린다.
+
+## 커밋
+
+지침의 변경은 `index.md`의 변경이다. 결정기록의 `docs`에 지침의 I- ID를 적는다. 폴더 안 다른 파일도 `paths`에 담아 함께 커밋할 수 있고, 그 파일만 바뀐 것에는 기록을 요구하지 않는다(`gitifact guide show commit`).
+
+## 에이전트
+
+- 요구사항·설계·코드를 바꾸기 전에 AGENTS.md 색인에서 작업 영역에 맞는 지침을 찾아 읽고 따른다. 맞는 지침이 없으면 없다고 보고 진행한다.
+- `gitifact instructions list`는 AGENTS.md가 있는지와 지침마다 딸린 파일 수를 보인다. 지침은 `instructions show <이름>`으로 `index.md`를, `instructions show <이름> --file references/<파일>`로 딸린 파일을 읽는다.
+- 요청이 지침과 어긋나면 진행 전에 알린다. 지침을 바꿀지는 사용자와 정한다.
+- 여러 기능에 걸친 규칙이나 결정을 새로 정하면 지침에 남길지 제안한다. 사용자가 동의하면 기존 지침을 고치거나 `gitifact instructions new`로 만들고 AGENTS.md 색인을 함께 고친다.
+- 0.7의 위키(`.gitifact/wiki/`)는 0.8.0에서 지침으로 바뀌었다. 위키 페이지가 남아 있으면 `check`가 `WIKI_REMOVED`로 알린다. 옮기는 절차는 `gitifact guide show migrate`를 따른다.

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

@@ -0,0 +1,139 @@
+---
+title: 0.7 프로젝트 전환
+description: schemaVersion 2 프로젝트를 0.8.0 문서 형식으로 옮기는 절차, 검증, 전환 커밋
+---
+
+사용자가 0.7 형식(`.gitifact/config.json`의 `schemaVersion: 2`) 프로젝트를 0.8.0 문서 형식(schemaVersion 3)으로 옮겨 달라고 하면 이 절차를 따른다. CLI에는 변환 명령이 없으므로 에이전트가 옛 파일을 직접 읽고 새 구조로 쓴다. 끝나면 "보고" 절의 형식으로 알린다.
+
+이 지침에서 `gitifact`는 이 지침을 출력한 CLI(0.8.0 이상)의 실행 방법이다. 0.7.x CLI는 쓰지 않는다. 0.8.0 CLI는 schemaVersion 2 프로젝트의 조회를 거부하므로, 3절에서 설정을 바꾸기 전까지는 파일을 직접 읽는다.
+
+## 1. 시작 전에 확인할 것
+
+- `git status`가 깨끗해야 한다. 커밋되지 않은 변경이나 staging이 있으면 멈추고 사용자에게 알린다.
+- 옛 형식으로 `.gitifact/`를 고친 **열린 브랜치**가 있으면 전환 전에 합치라고 사용자에게 알리고, 합칠지 계속할지 확인받는다. 전환 뒤에 옛 형식 브랜치를 합치면 두 형식이 섞이고 `gitifact check`가 실패한다.
+- 전환은 마지막에 한 커밋으로 남긴다. 커밋 권한이 있는지 사용자에게 확인한다. 가능하면 새 브랜치에서 작업하고 검증 뒤 합친다.
+- 새 형식은 이 지침의 3절이 전부 설명한다. 형식이 헷갈리면 프로젝트 밖의 빈 Git 저장소에서 `gitifact init`과 `gitifact specs new feature|requirement|design|instruction …`를 실행해 CLI가 만드는 뼈대를 보고, `gitifact check`로 맞는지 확인한다.
+
+## 2. 옛 형식 읽기
+
+| 옛 파일 | 형식 |
+| :--- | :--- |
+| `.gitifact/spec/<기능>/requirements.md` | 프론트매터 `id: S-…`, 본문 첫 줄 `# 기능 제목`. `# 제목`과 첫 `## ` 사이에 문단이 있으면 그것이 기능의 소개다. 요구사항마다 `## 요구사항 제목` 다음 줄에 `<!-- gitifact-req: R-… -->`, 그 아래부터 다음 `## `까지(코드 블록 안 제외)가 요구사항 본문 |
+| `.gitifact/spec/<기능>/design.md` (있을 때) | 프론트매터 `id`(기능과 같은 S-)와 선택적 `sources`(`title`, `path` 또는 `url`, `note`). 본문 첫 줄 `# 설계 제목`, 절 아래에 `<!-- gitifact-ref: R-…[, R-…] -->` |
+| `.gitifact/spec/<기능>/history.jsonl` | 한 줄에 `{"id":"H-…","requirements":[R-…],"designs":[S-…]?,"documents":[W-…]?,"reason":"…"}` |
+| `.gitifact/wiki/**/*.md` | 프론트매터 `id: W-…`, 본문 첫 줄 `# 페이지 제목` |
+| `.gitifact/wiki/history.jsonl` | 위와 같은 이유 줄. 대상은 주로 `documents` |
+
+시작 전에 개수를 세어 둔다: 기능(`requirements.md`) 수, 요구사항(`gitifact-req` 주석) 수, 설계(`design.md`) 수, 위키 페이지 수. 4절에서 대조한다.
+
+## 3. 새 구조로 옮기기
+
+모든 구조 정보는 프론트매터에만 둔다. 본문에는 `#` 제목과 `<!-- gitifact-` 주석을 쓰지 않는다(코드 블록 안은 예외). 제목(`title`)은 200자, 설명(`description`)은 300자 이하의 한 줄이며 모두 필수다.
+
+1. **설정:** `.gitifact/config.json`의 `schemaVersion`을 3으로 바꾼다. `baseline`은 그대로 둔다.
+2. **기능:** `.gitifact/spec/<기능>/index.md`를 만든다.
+   ```markdown
+   ---
+   id: S-…            # 옛 requirements.md의 id 그대로
+   title: 기능 제목    # 옛 # 제목 그대로
+   description: 이 기능이 무엇인지 한 줄
+   ---
+
+   (옛 파일의 소개 문단이 있으면 그대로, 없으면 이 기능의 범위와 목적을 한두 문장으로 쓴다. 본문은 필수)
+   ```
+3. **요구사항:** 요구사항마다 `.gitifact/spec/<기능>/requirements/<slug>.md`를 만든다. slug는 제목을 나타내는 영어 소문자·숫자·하이픈(80자 이하)이다. `order`는 옛 파일의 순서대로 10, 20, 30…이다. 본문은 옛 요구사항 본문을 **한 글자도 바꾸지 않고** 옮긴다(`###` 소제목도 그대로). 본문 앞뒤의 빈 줄만 잘라 낸다.
+   ```markdown
+   ---
+   id: R-…
+   title: 요구사항 제목
+   description: 무엇을 요구하는지 한 줄
+   order: 10
+   ---
+
+   (옛 본문 그대로)
+   ```
+4. **설계:** 옛 design.md가 있는 기능마다 `gitifact specs new design <기능>/overview --title "<옛 설계 제목>" --description "<한 줄>"`을 실행해 D- ID를 받는다. 이 명령이 만든 `design/overview.md`의 본문을 옛 설계 본문(첫 줄 `# 설계 제목`은 뺀다)으로 바꾸고 `draft: true` 줄을 지운다. 이어서:
+   - 옛 본문의 `<!-- gitifact-ref: … -->` 줄은 지우고, 거기 적힌 R- ID를 모두 모아 중복 없이 프론트매터 `requirements`에 적는다.
+   - 옛 `sources`는 `path`면 그 경로가 가리키는 위키 페이지의 W- ID로 `- id: W-…`(`note`가 있으면 함께), `url`이면 `- title: …` / `url: …`로 옮긴다. W-는 5단계에서 그 페이지를 옮긴 지침의 I-로 바뀐다.
+   - 본문의 나머지는 바꾸지 않는다. `specs new`가 넣은 `order: 10`은 그대로 둔다. 설계를 관점별 파일(data, interface, ui, errors 등)로 나누는 것은 전환 커밋에서 하지 않는다. 옮긴 본문을 대조할 수 있게 overview 하나로 옮기고, 나누기는 전환 뒤 별도 커밋으로 `gitifact guide show design`에 따라 한다.
+   - 결과의 프론트매터는 이 모양이다. 새 형식의 참고 문서에는 `title`이 없으므로, 위키 페이지를 가리키던 옛 `title`은 사라진다.
+     ```markdown
+     ---
+     id: D-…
+     title: 옛 설계 제목
+     description: 한 줄
+     order: 10
+     requirements:
+       - R-…
+       - R-…
+     sources:
+       - id: I-…
+         note: 옛 note (있을 때)
+       - title: 외부 문서 제목
+         url: https://…
+     ---
+     ```
+5. **위키 → 지침:** 0.8.0에서 위키는 프로젝트 지침으로 바뀌었다(`gitifact guide show instructions`). 위키 페이지가 `.gitifact/wiki/`에 남아 있으면 `check`가 `WIKI_REMOVED`로 막으므로 모든 페이지를 지침 폴더로 옮긴다. 옮기기 전에 어느 페이지가 어느 지침의 어느 파일이 되는지 표로 사용자에게 보여 주고 확인받는다. 사용자가 묶음을 바꾸면 그대로 따른다.
+
+   | 옛 위치 | 새 위치 |
+   | :--- | :--- |
+   | `wiki/README.md`(운영 방침·진입 페이지) | `init`이 만든 기본 방침(결정 기록을 `adr/`에 쌓는다는 내용) 그대로면 옮기지 않고 지운다. 프로젝트가 고쳤으면 루트 페이지처럼 지침 `overview`의 `index.md`로 옮긴다. 그 안의 위키 운영 규칙을 AGENTS.md로 옮길지는 6절에서 정한다 |
+   | 루트 페이지 `wiki/<이름>.md` | 지침 `<이름>`의 `index.md`. 대문자 이름은 소문자로 바꾼다(`ARCHITECTURE.md` → `architecture`) |
+   | 최상위 폴더 `wiki/<폴더>/` | 지침 `<폴더>`. 폴더의 `README.md`가 있으면 그것이 `index.md`, 나머지 페이지는 `references/<폴더 안 경로>` |
+   | 루트 페이지와 같은 이름의 폴더 | 한 지침으로 합친다. 루트 페이지가 `index.md`다 |
+
+   - 지침마다 `gitifact instructions new <이름> --title "<제목>" --description "<한 줄>"`을 실행해 I- ID를 받는다. 제목은 `index.md`가 될 페이지의 옛 제목이다. 그런 페이지가 없는 폴더는 폴더가 담은 주제로 제목을 짓는다(예: `handbook` → 작업 안내서). description에는 무엇을 담는지와 어떤 작업 때 읽는지를 쓴다.
+   - `index.md`가 될 페이지는 옛 본문의 첫 줄 `# 제목`을 빼고 나머지를 바꾸지 않고 옮긴다. `specs new`가 만든 본문을 이것으로 바꾸고 `draft: true` 줄을 지운다. 폴더에 `index.md`가 될 페이지가 없으면 본문에 references 파일마다 옛 제목과 링크를 한 줄씩 적는다.
+   - references로 옮기는 페이지는 옛 파일을 그대로(`# 제목` 줄 포함) 옮기고 프론트매터와 그 뒤 빈 줄만 지운다. 파일은 `# 제목`으로 시작한다. references 파일은 문서로 파싱하지 않으므로 ID가 없다.
+   - 위키 폴더에 있던 이미지 등 Markdown이 아닌 파일은 그것을 쓰는 지침 폴더로 옮긴다.
+   - 지침은 명세를 가리킬 수 없다(`INSTRUCTION_SPEC_LINK`). 옮긴 파일에서 `.gitifact/spec/` 아래로 가는 링크는 `[글자](경로)`를 링크 글자만 남긴다. 다른 상대 링크는 6단계에서 새 위치에 맞게 고친다.
+   - 4단계에서 위키 페이지 W-를 가리킨 설계 `sources`는 그 페이지가 옮겨 간 지침의 I-로 바꾼다. 한 설계가 같은 지침을 두 번 가리키게 되면 하나로 합치고 note를 `; `로 잇는다.
+   - 옛 W- ID는 문서에서 사라지고 0.7 커밋의 이유에만 남는다.
+   - 위키의 결정 기록(ADR) 페이지를 결정기록 파일로 바꾸거나 지침을 다시 묶는 일은 전환 커밋에서 하지 않는다. 옮긴 본문을 대조할 수 있게 그대로 옮기고, 다듬기는 전환 뒤 별도 커밋으로 한다.
+6. **상대 링크:** 요구사항·설계가 새 경로로 옮겨졌으므로, 문서 본문의 상대 링크 중 옛 `requirements.md`·`design.md`를 가리키거나 파일 위치가 바뀌어 깨지는 것을 새 경로로 고친다(요구사항·설계 본문은 한 단계 깊어졌다). 위키 페이지로 가던 링크는 그 페이지가 옮겨 간 지침 파일로, 옮긴 지침 파일 안의 링크는 새 위치 기준으로 고친다. 링크를 고치는 것 외에 본문을 다듬지 않는다.
+7. **이유:** 옛 history.jsonl의 이유는 옮기지 않는다. 0.7 커밋에 남아 있어 전환 뒤에도 이력(`records list --doc`, 브라우저)에 그대로 보인다. 0.8.0에서 새로 생기는 변경의 이유는 결정기록으로 남긴다(`gitifact guide show records`). 전환 커밋에는 결정기록을 쓰지 않는다. 전환 커밋은 이력에서 숨겨진다.
+8. **옛 파일 삭제:** 모든 `.gitifact/spec/<기능>/requirements.md`, `design.md`, `history.jsonl`과, 5단계에서 페이지를 모두 옮긴 `.gitifact/wiki/` 폴더 전체(`wiki/history.jsonl` 포함)를 일반 파일 삭제로 지운다. `git rm`은 staging을 만들어 5절의 커밋이 거부되므로 쓰지 않는다. 이미 staging됐다면 `git restore --staged <경로>`로 푼다.
+
+기계적인 부분(파일 나누기, 위키 페이지 옮기기)은 일회성 스크립트로 해도 된다. 스크립트는 프로젝트 밖에 두고 커밋하지 않는다. slug·description·기능 본문은 내용을 읽고 직접 쓴다. 기능·요구사항·지침마다 description이 하나씩 필요하므로 전환에서 가장 큰 일이다(기능 18개·요구사항 45개·지침 5개면 68개). description은 그 문서가 무엇을 요구하거나 다루는지를 목록에서 한 줄로 알아볼 수 있게 쓴다. 제목을 되풀이하지 말고 사용자 스토리나 첫 문단의 핵심을 줄인다.
+
+**예외로 허용되는 것:** 평소에는 ID를 CLI만 발급하고 커밋된 이유를 고치지 않는다. 이번 전환에서만 기존 S-·R- ID를 옮겨 적는다. 새 ID를 지어내지 않는다(설계 D-와 지침 I-는 `specs new`로 받는다).
+
+## 4. 검증
+
+1. `gitifact check`가 `문제 없음`이어야 한다. 문제가 있으면 고친다.
+2. 2절에서 센 개수와 대조한다: 기능 수 = `index.md` 수, 요구사항 수, 설계 수(기능별 `design/overview.md`), 위키 페이지 수(5단계 표의 `index.md`와 references 파일 수의 합). 문서는 `gitifact specs list --format json`과 `gitifact instructions list --format json`으로 센다.
+3. 옛 ID가 모두 새 문서에 있는지 확인한다. 옛 ID는 `git grep -ohE '(S|R)-[a-z2-7]{10}' HEAD -- .gitifact`의 정의 위치(프론트매터 `id`, `gitifact-req` 주석)에서, 새 ID는 `gitifact specs list --format json`의 `documents[].id`에서 모은다. `.gitifact/wiki/`와 `history.jsonl` 파일이 남지 않았고 설계 `sources`에 W-가 없어야 한다.
+4. `gitifact changes list`의 마지막에 `문서 검사: 문제 없음`이 나와야 한다. 이 시점의 다른 출력은 전환에서 정상이다: 옛 형식은 새 파서로 읽히지 않으므로 모든 문서가 `created`로 나온다. 새로 만든 문서에는 결정기록이 필요 없다. 커밋을 막지 않는다.
+
+## 5. 커밋
+
+`gitifact changes list`가 알려 준 입력 파일 경로에 JSON을 쓰고 `gitifact changes commit --file <그 경로>`를 실행한다. 먼저 `--dry-run`으로 확인한다. `paths`는 `git status --porcelain --untracked-files=all`에 나오는 경로 전부다(`.gitifact/cache/`는 스스로 제외되어 나오지 않는다). `evidence`에는 사용자가 전환과 커밋을 요청한 말을 인용한다.
+
+```json
+{
+  "paths": ["<바뀌거나 새로 생기거나 지워진 모든 경로: .gitifact/config.json, 새 문서들, 지운 옛 파일들>"],
+  "message": "chore(gitifact): migrate to the 0.8.0 document format",
+  "authorization": { "basis": "user-request", "evidence": "<사용자가 전환과 커밋을 요청한 말>" },
+  "migration": true
+}
+```
+
+- `migration: true`가 있어야 `Gitifact-Migration: 0.8.0` 트레일러가 붙는다. 이 커밋이 이력의 경계가 되어, 그 이전 활동은 뷰어에서 그대로 보이고 이 커밋은 활동에 나오지 않는다.
+- 결정기록은 넣지 않는다. 0.7 이유는 0.7 커밋에서 읽힌다.
+- 지운 옛 파일도 `paths`에 넣어야 한다. 빠지면 CLI가 거부한다.
+
+## 6. 전환 뒤 정리
+
+- 에이전트 지침 파일의 GITIFACT 블록을 `gitifact update`로 새 버전에 맞춘다. 블록 밖의 프로젝트 지침(AGENTS.md, CLAUDE.md 등)에 `spec working`, `spec save`, `spec commit`, `docs <topic>` 같은 옛 명령이 있으면 새 명령(`specs`·`instructions`·`records`의 `list`·`show`·`new`, `check`, `changes list`·`commit`, `guide show`)으로 바꿔 별도 커밋으로 남길지 사용자에게 묻는다.
+- 0.7.x 브라우저가 만든 옛 색인 `<git 공용 폴더>/gitifact/`(보통 `.git/gitifact/`)가 있으면 지워도 된다고 알린다. 0.8.0은 쓰지 않으며, 지우는 것은 사용자에게 맡긴다.
+- 0.8.0의 캐시는 `.gitifact/cache/`에 생기고 스스로 Git에서 제외된다. 첫 조회는 이력을 처음부터 읽어 몇 초 걸릴 수 있다.
+- 지침 `overview`로 옮긴 위키 README에 위키 운영 규칙(무엇을 어디에 쌓는지)이 있으면, 그 규칙을 AGENTS.md나 해당 지침으로 옮길지 사용자와 정한다. 이어서 AGENTS.md의 GITIFACT 블록 밖에 지침 색인을 적는다: 지침마다 어떤 작업 때 읽는지 한 줄(`gitifact guide show instructions`의 "AGENTS.md 색인"). 전환 커밋과 별도 커밋으로 남길지 사용자에게 묻는다.
+- references로 옮긴 결정 기록(ADR)을 결정기록(`gitifact guide show records`)으로 바꾸고 지침 본문에는 지키는 규칙만 남기는 정리, 지침을 다시 묶는 정리는 사용자와 정해 별도 커밋으로 한다. 전환 커밋은 숨겨지므로 이 커밋에서 쓴 결정기록이 이력에 보인다.
+- 전환 커밋에서는 본문을 다듬지 않았으므로, 지침이나 명세 본문에 `requirements.md`·`spec save` 같은 옛 형식 서술이나 위키를 가리키는 문장이 남아 있을 수 있다. 찾은 위치를 보고하고, 고치는 것은 사용자와 정해 별도 커밋으로 한다.
+
+## 7. 보고
+
+- 옮긴 개수: 기능·요구사항·설계·위키 페이지(옛 개수와 함께), 위키 페이지가 옮겨 간 지침 표
+- `check` 결과와 대조 결과
+- 고친 상대 링크, 옮기지 못했거나 판단이 필요했던 것
+- 커밋 해시(했다면), 남은 정리(지침의 옛 명령, 옛 색인)

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

@@ -0,0 +1,82 @@
+---
+title: 결정기록 형식
+description: 결정기록을 쓰는 때, 파일 형식과 섹션, 초안에서 커밋까지, 읽는 법
+---
+
+결정기록은 문서가 왜 지금 모양이 됐는지를 남긴다. 문서 본문에는 지금 유효한 내용만 있으므로, 본문이 스스로 설명하지 못하는 맥락과 고른 안을 기록으로 둔다. 기록은 한 번 커밋하면 고치지 않는다. 결정이 바뀌면 새 기록을 쓰고, 한 문서의 기록을 시간순으로 읽으면 결정의 흐름이 보인다.
+
+## 쓰는 때
+
+| 경우 | 기록 |
+| :--- | :--- |
+| 기존 요구사항·설계·지침의 내용을 바꾸거나 지움 | 쓴다. 옛 내용이 사라지므로 맥락을 남길 곳이 기록뿐이다 |
+| 새로 만들거나 바꾸면서 여러 안 중 하나를 고름 | 쓴다. 검토한 대안은 문서 본문에 두지 않는다 |
+| 새 요구사항을 그냥 추가 | 쓰지 않는다. 사용자 스토리가 이유다 |
+| 다른 결정에 딸려 고친 문서 | 따로 쓰지 않는다. 원래 결정의 `docs`에 그 문서를 더한다 |
+| 오타, 문장 다듬기 | 쓰지 않는다 |
+
+결정은 내린 순간에 기록한다. 커밋할 때 대화를 되짚어 쓰면 검토한 대안 같은 맥락이 사라진다. 한 작업에서 결정을 여러 번 하면 기록도 여럿이다.
+
+## 파일
+
+기록 하나는 `.gitifact/records/<yyyymmdd>/<DR-ID>.md` 파일 하나다. CLI로 만든다. CLI가 ID를 발급하고 오늘 날짜 폴더(그날 첫 기록 때 생긴다)에 필수 섹션과 `draft: true`를 넣어 쓴다.
+
+```text
+gitifact records new --title "삭제한 게시물의 30일 보관" --docs R-…,D-…
+```
+
+```markdown
+---
+id: DR-CLI가발급한값
+title: 삭제한 게시물의 30일 보관
+docs:
+  - R-바뀐요구사항의실제값
+  - D-바뀐설계의실제값
+---
+
+## 맥락
+
+실수로 지운 글을 되살려 달라는 문의가 한 달에 20건가량 들어온다.
+
+## 결정
+
+지운 게시물은 30일 동안 휴지통에 두고, 그 뒤 정리 작업이 영구 삭제한다.
+
+## 검토한 대안
+
+- 즉시 영구 삭제(복구 요청을 받을 수 없다)
+- 기간 없이 보관(저장 공간이 계속 는다)
+```
+
+위 ID와 문장은 구조 설명이다. 섹션을 채운 뒤 `draft: true` 줄을 지운다. 이 줄이 남은 기록은 커밋할 수 없다.
+
+- **`title`:** 80자 이내의 한 줄이다. 브라우저의 결정기록 화면과 `records list --doc`에서 기록의 이름이 된다. 대상과 동작을 뜻하는 명사로 끝나는 짧은 구로 쓴다(예: `섹션 500자 제한`, `문서 안 결정 표 폐지`, `커밋당 결정 하나 권장`). `~한다`·`~하기`로 끝내지 않고, 주제만 적지 않으며(`섹션 길이`가 아니라 `섹션 500자 제한`), 이유는 섹션에 둔다.
+- **`docs`:** 이 기록이 설명하는 문서의 ID다. 지우는 문서의 ID도 적을 수 있다. 딸려 고친 문서도 여기에 더한다.
+- **작성자·시각:** 파일에 쓰지 않는다. 기록을 더한 커밋에서 읽는다.
+
+| 섹션 | 필수 | 내용 |
+| :--- | :--- | :--- |
+| 맥락 | 예 | 무엇 때문에 결정이 필요했는지. 문제, 요청, 제약 |
+| 결정 | 예 | 무엇을 하기로 했는지 |
+| 검토한 대안 | 아니오 | 실제로 검토하고 고르지 않은 안과 그 까닭 |
+
+본문은 이 `##` 섹션으로만 쓴다. 섹션 제목은 한국어(`## 맥락`)나 영어(`## Context`)로 쓴다. 목록에 없는 섹션과 두 번 나오는 섹션은 `check`의 문제다. 검토한 대안은 실제로 따져 본 안이 있을 때만 쓰고 억지로 지어내지 않는다. 요구사항을 바꾸는 기록처럼 대안이 없으면 이 섹션을 뺀다.
+
+## 분량
+
+맥락과 결정은 각각 2~5문장으로 쓴다. 맥락에는 무엇이 문제였는지(드러난 현상과 잰 수치), 누가 무엇을 요청했는지, 지켜야 할 제약을 담는다. 결정에는 무엇을 하기로 했는지와 어디까지 적용하는지, 예외를 담는다. 근거가 없는 내용으로 문장 수를 채우지 않는다. 섹션 하나가 500자를 넘으면 `check`의 문제(`RECORD_SECTION_TOO_LONG`)다. 검토한 대안은 한 줄에 하나씩, 고르지 않은 까닭은 괄호로 짧게 쓴다. 경위, 측정 과정, 옛 방식의 설명은 쓰지 않는다. API 필드, 구현 절차, 테스트 기록은 기록에 옮기지 않고 설계나 커밋에 둔다. 긴 설명이 필요하면 그 내용은 설계나 지침 본문에 두고 기록에는 요지만 남긴다. 문체는 `gitifact guide show writing`을 따른다.
+
+## 커밋
+
+기록 파일은 설명하는 문서와 같은 커밋에 담는다. 커밋 입력의 `paths`에 기록 파일을 넣는다(`gitifact guide show commit`). 커밋 하나에 결정 하나를 기본으로 하며, 그 결정의 문서·코드·테스트를 함께 담는다. 한 파일이 두 결정에 걸치면 두 기록을 한 커밋에 담는다. `changes list`가 기록마다 설명하는 문서와 두 기록이 함께 설명하는 문서를 보여 준다.
+
+커밋한 기록은 고치거나 지우지 않는다. 고치면 `check`가 `RECORD_ALTERED`로 알리고 커밋이 거부된다. HEAD대로 되돌리고, 바뀐 결정은 새 기록으로 쓴다.
+
+## 읽기
+
+| 명령 | 쓰는 때 |
+| :--- | :--- |
+| `gitifact records list --doc <ID>` | 문서를 바꾸기 전에 그 문서의 결정 흐름을 읽는다. 기록마다 제목과 섹션, 커밋이 나온다 |
+| `gitifact records show <DR-ID>` | 기록 하나의 원문과 그것을 더한 커밋을 본다 |
+
+`.gitifact/records/`의 파일을 모두 읽거나 grep하지 않는다. 기록은 날짜와 ID로만 놓여 있어 문서별로 모으려면 전부 읽어야 한다. `records list --doc`은 캐시의 색인으로 바로 찾는다.

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

@@ -1,21 +1,41 @@
-# Markdown 명세 형식
+---
+title: 요구사항 형식
+description: 기능과 요구사항 파일의 구조, 프론트매터, 사용자 스토리와 수용 조건, 만들기·고치기·옮기기
+---
+
+기능 하나는 `.gitifact/spec/<기능>/` 폴더 하나다. 기능 소개는 `index.md`, 요구사항은 `requirements/<slug>.md`에 하나씩, 설계는 `design/` 아래 파일들(`gitifact guide show design`)이다. 문서가 왜 바뀌었는지는 결정기록(`.gitifact/records/`)이 남긴다(`gitifact guide show records`).
+
+```text
+.gitifact/spec/posts/
+  index.md                 기능 소개 (S-)
+  requirements/
+    create.md              요구사항 하나 (R-)
+    delete.md
+  design/
+    overview.md            설계 (D-)
+```
+
+## 만들기
 
-기능 명세는 `.gitifact/spec/<기능>/requirements.md` 하나에 그 기능의 요구사항을 담는다. 설계는 같은 폴더의 `design.md`(`gitifact docs design`), 변경 이유는 `history.jsonl`이다.
+파일은 CLI로 만든다. CLI가 ID를 발급하고 프론트매터를 채우며 본문 뼈대를 쓴다.
+
+```text
+gitifact specs new feature posts --title "게시물 관리" --description "게시물을 쓰고 고치고 지우는 기능"
+gitifact specs new requirement posts/create --title "게시물 등록" --description "작성자가 제목과 내용으로 게시물을 저장한다"
+```
 
-## 파일 구조와 ID
+만든 파일에는 `draft: true`가 붙는다. 본문을 채운 뒤 이 줄을 지우고 `gitifact check`로 확인한다. 이 줄이 남아 있으면 `check`와 `changes commit`이 실패한다. ID를 직접 만들거나 다른 문서의 ID를 복사하지 않는다.
 
-S-ID와 R-ID는 CLI가 발급한 값을 그대로 사용한다. 형식은 `S-<난수>`와 `R-<난수>`이며 난수는 소문자 base32 10자다. R-ID에 기능 이름을 넣거나 직접 예시 ID를 만들어 저장하지 않는다. 파일은 frontmatter로 시작하고, 요구사항 제목 바로 아래 줄에 ID 주석을 둔다.
+## 파일 구조
 
 ```markdown
 ---
-id: S-CLI가발급한값
+id: R-CLI가발급한값
+title: 게시물 등록
+description: 작성자가 제목과 내용으로 게시물을 저장한다
+order: 10
 ---
 
-# 게시물 관리
-
-## 게시물 등록
-<!-- gitifact-req: R-CLI가발급한값 -->
-
 게시물 작성자로서, 작성한 글을 나중에 다시 확인하기 위해 제목과 내용을 저장하고 싶다.
 
 ### 수용 조건
@@ -24,32 +44,47 @@ id: S-CLI가발급한값
    기대 동작: 시스템은 제목 입력 안내를 표시하고 저장을 중단합니다.
 ```
 
-위 ID는 구조 설명용이며 유효한 입력이 아니다. frontmatter에는 `id`만 둔다. 제목(`#`)은 한 번, 요구사항은 `##`이며 본문에 다른 gitifact 주석을 쓰지 않는다. 다른 문서로 가는 링크는 이 파일 기준 상대 경로로 쓴다(예: `../../wiki/architecture.md`, `../../assets/flow.png`). 브라우저가 그 링크를 해당 페이지로 연결하고, 대상이 없으면 `spec working`이 `MISSING_LINK_TARGET`으로 알린다.
+위 ID와 문장은 구조 설명이며 유효한 입력이 아니다.
 
-## 저장 명령
+- **`id`:** CLI가 발급한 값이다. 기능은 `S-`, 요구사항은 `R-`, 뒤는 소문자 base32 10자다. 파일을 옮기거나 제목을 바꿔도 그대로 둔다.
+- **`title`·`description`:** 필수이며 한 줄이다. 제목은 본문에 `#`로 다시 쓰지 않는다. 설명은 목록(`specs list`)에서 본문을 열지 않고도 무엇인지 알 수 있게 쓴다.
+- **`order`:** 요구사항에만 있다. 기능 안에서 사용 흐름에 맞는 순서로 매기고, 같은 기능에서 겹치면 안 된다. `specs new`는 그 폴더의 최댓값+10을 넣으므로 사이에 끼울 자리가 남는다.
+- **본문:** 비워 둘 수 없다. `#` 제목과 gitifact 주석(`<!-- gitifact-… -->`)을 쓰지 않는다. 기능 `index.md`의 본문은 그 기능이 무엇이고 어디까지인지를 한두 문단으로 쓴다.
 
-실제 저장은 `spec working`의 stamp로 다음 JSON을 구성해 working 결과의 `inputs.save` 경로에 쓰고 `spec save --file <그 경로>`를 호출한다. 성공하면 CLI가 입력 파일을 지운다. 실패하면 파일이 남으므로 고쳐서 다시 실행한다.
+프론트매터에 다른 키를 두지 않는다. 문서 사이의 관계는 설계의 `requirements`·`sources`로 나타내고, 요구사항이 어느 기능에 속하는지는 폴더가 정한다.
 
-```json
-{
-  "expected": "working의 실제 stamp",
-  "operations": [
-    { "type": "create", "feature": "posts", "title": "게시물 관리" },
-    { "type": "add", "feature": "posts", "title": "게시물 등록", "body": "게시물 작성자로서, 작성한 글을 나중에 다시 확인하기 위해 제목과 내용을 저장하고 싶다.\n\n### 수용 조건\n\n1. 조건: 사용자가 제목을 비운 채 저장을 요청합니다.\n   기대 동작: 시스템은 제목 입력 안내를 표시하고 저장을 중단합니다." },
-    { "type": "set-design", "feature": "posts", "title": "게시물 관리 설계", "body": "## 개요\n\n합의한 구현 방향과 범위.\n\n## 구조와 데이터\n\n실제 구현에 필요한 구성 요소와 저장 방식." }
-  ]
-}
-```
+다른 문서로 가는 링크는 이 파일 기준 상대 경로로 쓴다(요구사항에서 에셋으로는 `../../../assets/flow.png`). 브라우저가 해당 페이지로 연결한다. 대상이 없으면 `check`와 `changes list`가 `MISSING_LINK_TARGET` 경고로 알린다. 경고는 커밋을 막지 않는다.
+
+## 읽기
 
-명령 그룹은 `gitifact spec`이다. 기존 요구사항은 `update`의 id·title·body, 이동은 `move`의 id·feature, 명세 제목 변경은 `rename-spec`의 id·title을 사용한다. id에는 조회한 실제 R-ID 또는 S-ID를 전달한다. 전용 삭제·폴더 이름 변경 명령은 아직 없다. 미지원 작업에 존재하지 않는 명령이나 임의 전환 절차를 안내하지 않는다.
+| 명령 | 쓰는 때 |
+| :--- | :--- |
+| `gitifact specs list [--feature <기능>]` | 기능·요구사항·설계의 ID·제목·설명을 본문 없이 본다 |
+| `gitifact specs list --uncovered` | 어떤 설계도 다루지 않는 요구사항을 찾는다. `--without-design`은 설계 없는 기능, `--draft`는 초안이 남은 문서다 |
+| `gitifact specs list --changed-since <날짜\|커밋>` | 그 뒤에 바뀐 문서를 찾는다. `--author`, `--sort updated`와 함께 쓴다 |
+| `gitifact specs list --q <검색어>` | 제목이나 설명에 없는 내용을 본문에서 찾는다 |
+| `gitifact specs show <ID…>` | 고른 문서의 원문과 그 문서를 가리키는 설계를 본다. `--ref <커밋>`은 그 시점의 원문이다 |
+| `gitifact records list --doc <ID>` | 그 문서가 왜 바뀌어 왔는지 결정기록과 커밋을 본다 |
 
-설계는 `set-design`(type·feature·title·body·선택적 sources)으로 같은 요청에 담을 수 있다. 자세한 작성 규칙은 `gitifact docs design`, 위키와 에셋은 `gitifact docs wiki`를 읽는다.
+목록의 조건으로 고른 뒤 필요한 문서만 `show`로 읽는다. 목록은 `--fields id,title`처럼 필요한 열만, `--format json`으로도 받는다. 전체 파일을 grep하거나 모두 여는 것보다 적게 읽는다.
 
-본문의 문체는 `gitifact docs writing`을 따른다. 그 문서의 문체 규칙은 아래 사용자 스토리 문형과 `조건: / 기대 동작:` 형식을 대체하지 않는다.
+## 고치기·옮기기·지우기
+
+파일을 직접 고친다. 저장 명령은 없다. 고친 뒤에는 `gitifact check`로 형식과 참조를 확인한다.
+
+| 작업 | 방법 |
+| :--- | :--- |
+| 내용 고치기 | 파일의 `title`·`description`·본문을 고친다. ID는 그대로 둔다 |
+| 다른 기능으로 옮기기 | 파일을 그 기능의 `requirements/`로 옮기고 ID를 유지한다. 옮긴 곳의 순서에 맞게 `order`를 고친다 |
+| slug 바꾸기 | 파일 이름만 바꾼다. ID와 내용은 그대로다 |
+| 지우기 | 파일을 지운다. 그 요구사항을 가리키던 설계의 `requirements`에서 ID를 빼야 `check`가 통과한다 |
+| 기능 이름(폴더) 바꾸기 | 폴더를 옮긴다. `index.md`의 S- ID는 그대로다 |
+
+옮기거나 이름을 바꿀 때 새 ID로 복제하지 않는다. 지운 ID를 다른 문서에 다시 쓰지 않는다. 요구사항을 바꾸면 그것을 가리키는 설계도 확인한다(`specs show <R-ID>`의 "가리키는 문서").
 
 ## 기능으로 묶는 기준
 
-사용자에게 의미 있는 응집된 기능으로 명세를 묶는다. 코드 모듈이나 DDD 계층을 그대로 복제하지 않는다. 기존 명세에 포함할 수 있는지 먼저 확인한다. 제목·폴더가 달라져도 같은 요구사항의 ID는 유지하며, 실제 잘못 배치된 요구사항을 옮길 때도 새 ID로 복제하지 않는다. 명세 제목은 기능 이름 그대로 쓰고 "요구사항" 같은 접미어를 붙이지 않는다.
+사용자에게 의미 있는 응집된 기능으로 묶는다. 코드 모듈이나 DDD 계층을 그대로 복제하지 않는다. 새 기능을 만들기 전에 기존 기능에 넣을 수 있는지 먼저 확인한다. 기능 제목은 기능 이름 그대로 쓰고 "요구사항" 같은 접미어를 붙이지 않는다. slug와 폴더 이름은 소문자·숫자·하이픈이다.
 
 ## 사용자 스토리와 수용 조건
 
@@ -57,6 +92,8 @@ id: S-CLI가발급한값
 
 사용자 스토리 아래에는 `### 수용 조건`과 번호별 `조건: / 기대 동작:` 형식을 유지한다. 파일 경로·ID·저장 규약으로 사용자 목표를 대신하지 않는다. 별도로 필요한 확정 제약은 `### 범위와 제약`에 두고, 내부 구현 방식은 설계에 둔다. 역할·목표·이유는 대화와 확인한 맥락에 근거하며, 모르는 동기를 만들어 문형을 채우지 않는다. 의미를 결정할 정보가 부족하면 필요한 부분만 질문한다.
 
-새 요구사항과 요청받아 개정하는 요구사항에 적용한다. 기존 문서를 정리할 때 ID·확정된 제약·수용 조건의 의미를 보존하고, 이번 작업과 무관한 요구사항을 일괄 개정하지 않는다. 저장 전에는 스토리의 역할·목표·이유가 드러나는지, 수용 조건이 그 목표의 성공·실패를 판정하는지 대조한다. CLI는 특정 문장이나 사용자 의도를 강제·검증하지 않는다.
+새 요구사항과 요청받아 개정하는 요구사항에 적용한다. 기존 문서를 정리할 때 ID·확정된 제약·수용 조건의 의미를 보존하고, 이번 작업과 무관한 요구사항을 일괄 개정하지 않는다. 다 쓴 뒤에는 스토리의 역할·목표·이유가 드러나는지, 수용 조건이 그 목표의 성공·실패를 판정하는지 대조한다. CLI는 특정 문장이나 사용자 의도를 강제·검증하지 않는다.
+
+본문의 문체는 `gitifact guide show writing`을 따른다. 그 문서의 문체 규칙은 위 사용자 스토리 문형과 `조건: / 기대 동작:` 형식을 대체하지 않는다.
 
-대화 중에는 명세 초안을 다듬는다. 매 수정마다 이유나 사건을 쌓지 않는다. 코드와 테스트를 고치는 동안 달라진 요구사항은 마지막 합의 내용으로 맞춘다.
+대화 중에는 파일을 다듬는다. 기존 요구사항을 바꾸거나 여러 안 중 하나를 고르면 그때 결정기록 초안을 쓴다(`gitifact guide show records`). 새 요구사항을 추가하기만 하면 기록은 필요 없다. 코드와 테스트를 고치는 동안 달라진 요구사항은 마지막 합의 내용으로 맞춘다.

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

@@ -1,42 +1,54 @@
-# gitifact 작업 흐름
+---
+title: gitifact 작업 흐름
+description: 시작할 때 확인할 것, 요구사항으로 남길 요청의 구분, 마무리 보고
+---
 
 사용자는 제품을 설명하고 개발을 이어간다. 에이전트는 제품 요구사항을 정리하고, 커밋할 때 최종 변경을 연결한다. 사용자가 기록 명령이나 별도 개발 방법론을 익히게 하지 않는다.
 
 ## 시작과 형식 확인
 
-현재 경로·브랜치·Git 상태와 기존 staging을 확인하고 적용되는 AGENTS.md·CLAUDE.md를 원문으로 읽는다. 지침에서 지정한 CLI를 사용한다. 아래 `gitifact`는 그 실행 방법을 뜻한다. CLI가 없다면 이 프로젝트에 참여하는 데 필요한 도구가 빠진 것이다. 설치·전역 설정 변경을 임의로 하지 않고, 사용자에게 알린 뒤 동의를 받아 블록 첫머리에 적힌 버전으로 설치한다(`npm install -g gitifact@<버전>`). 설치 전에는 가능한 조사부터 진행하고 명세 저장·커밋을 추측으로 대신하지 않는다.
+현재 경로·브랜치·Git 상태와 기존 staging을 확인하고 적용되는 AGENTS.md·CLAUDE.md를 원문으로 읽는다. 프로젝트가 정한 CLI 실행 방법을 우선하고, 별도 지정이 없으면 전역 `gitifact`를 쓴다. 먼저 `gitifact --version`이 블록 첫머리의 버전과 같은지 확인한다. 명령이 없거나 버전이 다르면 사용자에게 `npm install -g gitifact@<버전>` 설치를 제안하고, 설치 전까지와 원하지 않을 때는 `npx --yes gitifact@<버전> <명령>`으로 실행한다. 아래 `gitifact`는 선택한 실행 방법을 뜻한다. 전역 설치본은 PC에 한 버전뿐이므로 버전이 다른 전역 명령으로 이 프로젝트를 다루지 않는다. npx는 같은 버전의 프로젝트 의존성이 있으면 사용하고, 없으면 npm 캐시에 받아 실행한다.
+
+전역 명령이 없거나 전역 설치 권한이 없다는 이유만으로 Gitifact 작업을 건너뛰지 않는다. 전역 설치는 제안이며 사용자가 동의했을 때만 실행하고, 프로젝트 의존성 추가는 사용자가 그 방식을 선택했을 때 한다. 실행·네트워크 권한이 막히면 필요한 승인을 요청하고 원인을 알린다. `--yes`는 npm의 설치 확인만 생략하며 실행 환경의 권한을 바꾸지 않는다. 가능한 조사는 계속하되 CLI 실행 없이 문서 ID 발급·검사·커밋을 대신하거나 완료했다고 보고하지 않는다.
+
+새 세션에서는 지정 버전으로 `gitifact update --check`를 한 번 실행한다. 이 명령은 파일·index·커밋을 바꾸지 않는다. `available`이면 현재·새 버전을 알려 주고 업데이트할지 묻는다. 동의 전에는 지침을 갱신하거나 새 버전으로 작업하지 않는다. 거절하면 지정 버전으로 계속하며 같은 세션에서 다시 묻지 않는다. `unavailable`은 확인 실패이며 최신이라는 뜻이 아니다. 실패하거나 `GITIFACT_NO_UPDATE_CHECK`로 조회를 껐으면 지정 버전으로 작업을 이어간다.
+
+업데이트는 프로젝트의 실행 방식을 따른다. 전역 설치본을 쓰면 `npm install -g gitifact@<새 버전>`으로 올린 뒤 `gitifact update`를 실행해 블록의 버전을 갱신한다. npx를 쓰면 `npx --yes gitifact@<새 버전> update`를 실행한다. 프로젝트 의존성으로 관리하면 해당 패키지 관리자로 버전을 올리고 업데이트한 설치본을 실행한다.
 
 설정과 실제 파일, CLI 도움말을 함께 확인해 다음 중 하나의 흐름을 선택한다. 명령이 존재한다는 사실만으로 프로젝트 사용이나 전환이 허용되지는 않는다.
 
-- **현재 형식:** config.json의 `schemaVersion: 2`는 `.gitifact/spec/<기능>/requirements.md`, 선택적인 `design.md`, `history.jsonl`과 `.gitifact/wiki/`, `.gitifact/assets/`를 사용한다. `gitifact docs spec`·`docs wiki`의 형식을 따른다.
-- **이전 형식:** `schemaVersion: 1`(0.4.x)과 workflow-1·prototype-1·init-1 설정은 현재 CLI가 조회·기록하지 않는다. 기존 기록을 삭제하거나 새 형식으로 가장하지 않고, 정식 버전 전 규약이라 전환 도구가 없다고 알린다. 사용자가 원하면 기록을 보존한 채 새로 도입한다.
+- **현재 형식:** config.json의 `schemaVersion: 3`은 기능 폴더(`.gitifact/spec/<기능>/`의 `index.md`, `requirements/`, `design/`), 지침 폴더 `.gitifact/instructions/`, `.gitifact/assets/`와 결정기록 `.gitifact/records/`를 쓴다. 형식은 `gitifact guide show spec`·`design`·`instructions`·`records`를 따른다. 0.8.0 개발판의 이유 파일 `.gitifact/history.jsonl`이 남아 있으면 `check`가 `REASONS_FILE_REMOVED`로 알린다. 0.7의 위키 `.gitifact/wiki/`는 쓰지 않으며, 남은 페이지는 `check`가 `WIKI_REMOVED`로 알린다.
+- **0.7 형식:** `schemaVersion: 2`(기능마다 `requirements.md`와 `design.md` 한 파일)는 문서·결정기록·`changes` 명령이 읽지 않고 전환을 안내한다. 사용자가 전환에 동의하면 `gitifact guide show migrate`의 절차를 따른다. 동의 전에 파일을 옮기거나 새 형식으로 가장하지 않는다.
+- **더 이전 형식:** `schemaVersion: 1`(0.4.x)과 workflow-1·prototype-1·init-1 설정은 현재 CLI가 조회·기록하지 않는다. 기존 기록을 삭제하거나 새 형식으로 가장하지 않고, 정식 버전 전 규약이라 전환 도구가 없다고 알린다. 사용자가 원하면 기록을 보존한 채 새로 도입한다.
 - **미도입:** 도입이 허용됐으면 Git 상태와 지침을 확인하고 `init --dry-run`, `init`으로 연결한다. Git 저장소가 없으면 Git 생성 권한을 확인한다. 기존 변경과 staging을 보존한다.
 
-init은 `.gitifact/config.json`과 도입 기준선, 위키 운영 방침을 담은 `.gitifact/wiki/README.md`를 만들고, AGENTS.md 등 에이전트 지침 파일에 `<!-- GITIFACT:START -->`와 `<!-- GITIFACT:END -->` 사이의 블록을 쓴다. 블록이 AGENTS.md에 들어가고 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄짜리 CLAUDE.md를 함께 만든다. 마커 바깥의 내용은 건드리지 않는다. 요구사항·커밋은 만들지 않는다. 블록은 규칙의 요약이며, 상세 형식은 `gitifact docs <topic>`으로 읽는다. CLI를 업데이트한 뒤 `update`(또는 `init`)를 실행하면 블록이 갱신된다. 기존 블록의 언어는 유지하며, `--lang ko` 또는 `--lang en`을 지정한 경우에만 바꾼다. 새 블록은 CLI 언어를 따르고 프로젝트 문서는 기존 언어를 유지한다. `update`는 새 버전 여부와 설치 방법도 알려 주며 설치를 직접 실행하지는 않는다. 사용자가 업데이트를 요청하면 `update --commit`을 쓴다. 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋하고, 다른 staging은 그대로 둔다. 블록 밖에도 수정이 있거나 추적하지 않는 파일이거나 Git이 커밋을 거부하면 커밋하지 않고 `commit.reason`으로 알린다. 이때 에이전트가 메시지를 바꿔 대신 커밋하지 않고 사용자에게 알린다.
+init은 `.gitifact/config.json`과 도입 기준선을 만들고, AGENTS.md 등 에이전트 지침 파일에 `<!-- GITIFACT:START -->`와 `<!-- GITIFACT:END -->` 사이의 블록을 쓴다. 블록이 AGENTS.md에 들어가고 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄짜리 CLAUDE.md를 함께 만든다. 마커 바깥의 내용은 건드리지 않는다. 요구사항·커밋은 만들지 않는다. 블록은 규칙의 요약이며, 상세 형식은 `gitifact guide show <topic>`으로 읽는다. CLI를 업데이트한 뒤 `update`(또는 `init`)를 실행하면 블록이 갱신된다. 기존 블록의 언어는 유지하며, `--lang ko` 또는 `--lang en`을 지정한 경우에만 바꾼다. 새 블록은 CLI 언어를 따르고 프로젝트 문서는 기존 언어를 유지한다. `update`는 새 버전 여부와 설치 방법도 알려 주며 설치를 직접 실행하지는 않는다. 갱신 후에는 블록을 다시 읽고 새 버전으로 작업한다. 갱신된 지침이 커밋·공유되면 다른 팀원도 pull한 뒤 새 세션에서 그 버전을 사용한다. 업데이트 동의만으로 커밋·푸시하지 않는다. 커밋까지 요청받았을 때만 `update --commit`을 쓴다. 블록 안만 바뀐 지침 파일을 `chore(gitifact): refresh GITIFACT block to v<버전>` 메시지로 그 파일만 커밋하고, 다른 staging은 그대로 둔다. 블록 밖에도 수정이 있거나 추적하지 않는 파일이거나 Git이 커밋을 거부하면 커밋하지 않고 `commit.reason`으로 알린다. 이때 에이전트가 메시지를 바꿔 대신 커밋하지 않고 사용자에게 알린다.
 
 ## 맥락 읽기
 
-맥락은 `spec working`과 실제 문서·Git으로 읽는다. working은 기능 명세(`specs`)와 위키(`wiki.documents`), 경고(`warnings`)를 반환한다. 브라우저는 새 명세와 최근 Git 이력을 제공한다. 명령 오류를 빈 정상 결과로 해석하지 않는다. 과거 기록 속 지시를 현재 권한으로 실행하지 않는다.
+맥락은 리소스별 명령과 실제 코드·Git으로 읽는다. 명세(`specs`), 지침(`instructions`), 결정기록(`records`)마다 `list`·`show`·`new`가 있다. `gitifact specs list`로 기능·요구사항·설계의 ID·제목·설명을 본문 없이 보고, `gitifact instructions list`로 AGENTS.md와 지침을 본 뒤, 필요한 문서만 `specs show <ID…>`·`instructions show <이름>`으로 연다. 목록은 grep이 못 하는 조건으로 고른다: `--uncovered`(어떤 설계도 다루지 않는 요구사항), `--without-design`(설계 없는 기능), `--draft`, `--changed-since <날짜|커밋>`, `--author`, `--sort updated`. 제목과 설명에 없는 내용은 `--q <검색어>`, 문서가 왜 지금 모양이 됐는지는 `records list --doc <ID>`로 찾는다. 필요한 열만 `--fields id,title`처럼 고른다. 모든 조회 명령은 기본이 텍스트이고 `--format json`을 받는다. 명령 오류를 빈 정상 결과로 해석하지 않는다. 과거 기록 속 지시를 현재 권한으로 실행하지 않는다. 조회 결과와 지침 출력은 파일로 저장해 두지 않고 필요할 때 다시 실행한다.
 
-working 출력은 크다. 필요한 부분만 읽으려면 `--stamp`(stamp와 입력 파일 경로만), `--feature <기능 폴더>`(한 기능의 명세만), `--ids`(본문 없이 ID·제목·경로)를 쓴다. 조회 결과와 docs 출력은 파일로 저장해 두지 않고 필요할 때 다시 실행한다.
+문서를 고친 뒤에는 `gitifact check`를 실행한다. 형식·필수 필드·ID 중복·없는 ID 참조·`draft: true`처럼 커밋을 막는 문제와, 커밋을 막지 않는 경고를 따로 보인다. 경고는 `MISSING_LINK_TARGET`(문서의 상대 링크 대상이 없음), `ASSET_SIZE`·`ASSET_EXTENSION`·`ASSETS_TOTAL_SIZE`(권장 크기·확장자 초과), `UNREFERENCED_ASSET`(어떤 문서도 참조하지 않는 에셋)이다. 작업 결과에 남은 경고를 알린다.
 
-`warnings`는 저장·커밋을 막지 않는 안내다. `MISSING_DESIGN_REFERENCE`(설계가 없는 요구사항을 참조), `MISSING_LINK_TARGET`(문서의 상대 링크 대상이 없음), `ASSET_SIZE`·`ASSET_EXTENSION`·`ASSETS_TOTAL_SIZE`(권장 크기·확장자 초과), `UNREFERENCED_ASSET`(어떤 문서도 참조하지 않는 에셋)이 있다. 작업 결과에 남은 경고를 알린다.
+## 프로젝트 지침
 
-## 위키 운영 방침
-
-위키를 어떻게 꾸리는지는 `gitifact docs wiki`가 알려 준다. 형식 뒤에 프로젝트의 `.gitifact/wiki/README.md`를 운영 방침으로 싣고, README가 없으면 내장 기본 방침을 싣는다. 사용자가 위키 운영 방식을 바꾸고 싶다고 하면 README를 함께 고친다. 형식과 `spec save`의 검증은 README와 무관하게 유지된다.
+이 프로젝트에서 어떻게 일하는지는 `.gitifact/instructions/`의 지침이 담고, 어떤 작업 때 어느 지침을 읽을지는 AGENTS.md의 GITIFACT 블록 밖 색인이 알린다. 형식과 색인 쓰는 법은 `gitifact guide show instructions`를 따른다. 사용자가 일하는 방식을 바꾸고 싶다고 하면 해당 지침과 색인을 함께 고친다.
 
 ## 작업 중 임시 파일
 
-save·commit 입력 JSON은 `spec working`(또는 `spec changes`) 결과의 `inputs.save`·`inputs.commit` 경로에 만든다. 기본은 운영체제 임시 폴더 아래의 프로젝트별 폴더이고, 그곳에 쓸 수 없는 환경에서는 Git이 무시하는 `.gitifact/tmp/`다. 명령이 성공하면 CLI가 그 입력 파일을 지우고 결과에 `inputRemoved`를 싣는다. 실패·`--dry-run`·결과가 불확실한 커밋에서는 파일이 남으므로 원인을 고친 뒤 같은 파일로 다시 실행한다. 이 폴더의 7일 넘은 파일은 working 실행 때 정리된다. 짧은 입력은 `--file -`로 표준 입력에 넘겨도 되지만, 여러 줄 본문과 따옴표가 셸에서 깨질 수 있으면 파일을 쓴다. 프로젝트 안에 입력·출력 사본을 따로 만들지 않는다.
+커밋 입력 JSON은 `gitifact changes list`가 알려 주는 입력 파일 경로(JSON의 `inputs.commit`)에 만든다. 기본은 운영체제 임시 폴더 아래의 프로젝트별 폴더이고, 그곳에 쓸 수 없는 환경에서는 Git이 무시하는 `.gitifact/tmp/`다. 커밋이 성공하면 CLI가 그 입력 파일을 지우고 결과에 `inputRemoved`를 싣는다. 실패·`--dry-run`·결과가 불확실한 커밋에서는 파일이 남으므로 원인을 고친 뒤 같은 파일로 다시 실행한다. 이 폴더의 7일 넘은 파일은 `changes list` 실행 때 정리된다. 짧은 입력은 `--file -`로 표준 입력에 넘겨도 되지만, 여러 줄 본문과 따옴표가 셸에서 깨질 수 있으면 파일을 쓴다. 프로젝트 안에 입력·출력 사본을 따로 만들지 않는다.
 
 ## 기록을 보여 달라는 요청
 
-사용자가 요구사항·프로젝트 현황·변경 이력·패치노트를 보여 달라고 하면 `gitifact browser`를 실행하고 출력된 URL을 알려 준다. 이 명령은 URL을 출력한 뒤 서버로 계속 실행되므로 백그라운드로 띄운다. 끝나기를 기다리면 작업이 멈춘다. working JSON을 읽어 채팅에 요약하는 것으로 대신하지 않는다. 사용자가 특정 내용을 설명해 달라고 한 경우는 따른다. 이번 대화에서 이미 띄운 서버가 살아 있으면 새로 띄우지 않고 그 URL을 다시 알려 준다. 기본 브라우저를 직접 여는 것은 사용자가 요청할 때만 한다.
+사용자가 요구사항·프로젝트 현황·변경 이력·패치노트를 보여 달라고 하면 `gitifact browser`를 실행하고 출력된 URL을 알려 준다. 이 명령은 URL을 출력한 뒤 서버로 계속 실행되므로 백그라운드로 띄운다. 끝나기를 기다리면 작업이 멈춘다. 목록 출력을 읽어 채팅에 요약하는 것으로 대신하지 않는다. 사용자가 특정 내용을 설명해 달라고 한 경우는 따른다. 이번 대화에서 이미 띄운 서버가 살아 있으면 새로 띄우지 않고 그 URL을 다시 알려 준다. 기본 브라우저를 직접 여는 것은 사용자가 요청할 때만 한다.
+
+## Gitifact에 의견 보내기
+
+사용자가 Gitifact 자체의 버그나 개선을 남기고 싶어 하면 종류(`bug`·`idea`)와 제목·본문 초안을 쓰고 사용자에게 보여 준다. 본문에는 사용자가 겪은 일과 재현 절차를 쓰고, 프로젝트 파일·문서 내용·경로는 사용자가 넣으라고 한 것만 넣는다. 확인받기 전에는 보내지 않는다. 확인받으면 입력 파일에 `{"type": "bug", "title": "…", "body": "…"}`를 써서 `gitifact feedback --file <경로>`를 실행한다. 보낼 방법과 CLI가 붙이는 환경 정보(버전·운영체제·Node·저장 규약 버전)를 먼저 보이려면 `--dry-run`을 쓴다. CLI는 로그인된 `gh`가 있으면 사용자 계정으로 이슈를 만들고, 없으면 이슈 작성 페이지 주소를 출력한다. 주소를 사용자에게 알려 브라우저에서 제출하게 하고, 본문이 잘렸다고 나오면 전체 본문도 함께 전한다.
 
 ## 마무리
 
-정리한 요구사항과 실제 수행한 검증, 커밋 여부, 남은 제한을 짧게 알린다. 파일 저장·커밋·승인·구현·검증 완료를 구분한다. 독립 에이전트의 행동 시험, 마이그레이션, 새 GUI 연결은 실제 수행하지 않았다면 완료로 보고하지 않는다.
+정리한 요구사항과 실제 수행한 검증, 커밋 여부, 남은 제한을 짧게 알린다. 문서 수정·검사 통과·커밋·구현·검증 완료를 구분한다. 독립 에이전트의 행동 시험, 마이그레이션, 새 GUI 연결은 실제 수행하지 않았다면 완료로 보고하지 않는다.
 
 ## 무엇을 요구사항으로 남기는가
 
@@ -51,12 +63,12 @@ save·commit 입력 JSON은 `spec working`(또는 `spec changes`) 결과의 `inp
 | 테두리 색을 조금 연하게 해주세요 | 보통 스타일 수정이다. 매번 요구사항을 만들지 않는다. |
 | 선택한 항목은 테두리로 구분해주세요 | 선택 상태를 전달하는 동작이므로 기존 선택 요구사항의 수용 조건에 반영한다. |
 
-전체 화면의 일관된 표현 규칙은 위키의 규칙 페이지에 두고 기능별로 반복 등록하지 않는다. 분류는 표현 하나보다 실제 제품 의미와 기존 맥락으로 판단한다.
+전체 화면의 일관된 표현 규칙은 프로젝트 지침에 두고 기능별로 반복 등록하지 않는다. 분류는 표현 하나보다 실제 제품 의미와 기존 맥락으로 판단한다.
 
 ## 대화에서 정리하는 순서
 
 처음에는 사용 대상·원하는 결과·핵심 흐름·실패 조건·제품 제약을 대화에서 파악한다. 이미 답이 있는 질문을 반복하거나 긴 설문을 강제하지 않는다. 구현 방향을 바꾸는 불명확한 점만 묻고 독립적으로 가능한 작업은 진행한다.
 
-요구사항·설계·코드를 바꾸기 전에 `gitifact docs wiki`의 운영 방침에 따라 작업 영역에 맞는 위키 페이지를 읽고 따른다. 위키 페이지가 없으면 없다고 보고 진행한다. 요청이 위키에 적힌 범위 밖이거나 원칙과 어긋나면 진행 전에 알린다.
+요구사항·설계·코드를 바꾸기 전에 AGENTS.md 색인에서 작업 영역에 맞는 지침을 찾아 읽고 따른다. 맞는 지침이 없으면 없다고 보고 진행한다. 요청이 지침과 어긋나면 진행 전에 알린다.
 
 기존 프로젝트는 변경하는 영역부터 점진적으로 정리한다. 전체 기능 도출은 요청받았을 때 한다. 코드·테스트·문서·Git·대화 중 이용 가능한 자료를 읽으며 특정 docs 구조를 요구하지 않는다. 관측한 구현과 사용자의 의도, 향후 제안을 구분한다. 불확실한 후보는 질문과 근거로 제시하고 확정된 제품 요구사항처럼 저장하지 않는다. 과거 승인·구현 완료를 만들어내거나 커밋에 참조를 소급하지 않는다.