gitifact 0.8.2 → 0.8.4

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

@@ -7,13 +7,13 @@ description: 시작할 때 확인할 것, 요구사항으로 남길 요청의
 
 ## 시작과 형식 확인
 
-현재 경로·브랜치·Git 상태와 기존 staging을 확인하고 적용되는 AGENTS.md·CLAUDE.md를 원문으로 읽는다. 프로젝트가 정한 CLI 실행 방법을 우선하고, 별도 지정이 없으면 전역 `gitifact`를 쓴다. 먼저 `gitifact --version`이 블록 첫머리의 버전과 같은지 확인한다. 명령이 없거나 버전이 다르면 사용자에게 `npm install -g gitifact@<버전>` 설치를 제안하고, 설치 전까지와 원하지 않을 때는 `npx --yes gitifact@<버전> <명령>`으로 실행한다. 아래 `gitifact`는 선택한 실행 방법을 뜻한다. 전역 설치본은 PC에 한 버전뿐이므로 버전이 다른 전역 명령으로 이 프로젝트를 다루지 않는다. npx는 같은 버전의 프로젝트 의존성이 있으면 사용하고, 없으면 npm 캐시에 받아 실행한다.
+현재 경로·브랜치·Git 상태와 기존 staging을 확인하고 적용되는 AGENTS.md·CLAUDE.md를 원문으로 읽는다. 프로젝트가 정한 CLI 실행 방법을 우선하고, 별도 지정이 없으면 전역 `gitifact`를 쓴다. 아래 `gitifact`는 선택한 실행 방법을 뜻한다. 전역 설치본은 PC에 한 버전뿐이며, 그 버전이 프로젝트 기준과 다르면 명령마다 안내가 나온다.
 
-전역 명령이 없거나 전역 설치 권한이 없다는 이유만으로 Gitifact 작업을 건너뛰지 않는다. 전역 설치는 제안이며 사용자가 동의했을 때만 실행하고, 프로젝트 의존성 추가는 사용자가 그 방식을 선택했을 때 한다. 실행·네트워크 권한이 막히면 필요한 승인을 요청하고 원인을 알린다. `--yes`는 npm의 설치 확인만 생략하며 실행 환경의 권한을 바꾸지 않는다. 가능한 조사는 계속하되 CLI 실행 없이 문서 ID 발급·검사·커밋을 대신하거나 완료했다고 보고하지 않는다.
+설치와 업데이트는 에이전트가 한다. 사용자에게 명령을 건네 직접 설치하게 하지 않는다. 명령이 없으면 `.gitifact/config.json`의 `cli`(프로젝트가 기준으로 삼는 CLI 버전)로 `npm install -g gitifact@<버전>`을, 업데이트는 안내의 설치 명령을 그대로 보여 주며 실행해도 되는지 묻는다. 질문에 정확한 명령이 들어 있어야 사용자의 짧은 허용이 그 명령에 대한 허용으로 읽힌다. 허용하면 직접 실행한다. 에이전트 도구가 실행을 막으면 그 도구의 방식으로 승인을 요청한다. 샌드박스 밖 실행을 요청하면 승인 창이 뜨는 도구는 그 요청을 하고, 설정으로만 허용되는 도구는 어느 설정에 무엇을 더하면 되는지 알린다. Windows PowerShell에서 스크립트 실행이 막혀 있으면(`npm.ps1`을 로드할 수 없음) `npm.cmd`·`gitifact.cmd`로 실행한다. 설치가 끝나기 전에도 가능한 조사는 계속하되, CLI 실행 없이 문서 ID 발급·검사·커밋을 대신하거나 완료했다고 보고하지 않는다.
 
-새 세션에서는 지정 버전으로 `gitifact update --check`를 한 번 실행한다. 이 명령은 파일·index·커밋을 바꾸지 않는다. `available`이면 현재·새 버전을 알려 주고 업데이트할지 묻는다. 동의 전에는 지침을 갱신하거나 새 버전으로 작업하지 않는다. 거절하면 지정 버전으로 계속하며 같은 세션에서 다시 묻지 않는다. `unavailable`은 확인 실패이며 최신이라는 뜻이 아니다. 실패하거나 `GITIFACT_NO_UPDATE_CHECK`로 조회를 껐으면 지정 버전으로 작업을 이어간다.
+모든 명령은 결과보다 먼저 stderr에 버전 안내를 한 줄 낼 수 있다. JSON 출력은 바뀌지 않는다. 프로젝트 기준이 실행 중인 CLI보다 새 버전이면 그 버전의 설치를, 새 버전이 나왔으면 설치 후 `gitifact update`를, 실행 중인 CLI가 프로젝트 기준보다 새 버전이면 `gitifact update`로 기준을 올리라고 알린다. 한 번에 하나만 이 순서로 낸다. 새 버전 확인은 사용자 캐시만 읽고, 마지막 확인이 1시간을 넘으면 명령과 따로 뒤에서 레지스트리를 조회해 캐시를 갱신한다. 안내가 보이면 다음 작업 전에 설치 명령을 보여 주며 지금 업데이트(권장)와 나중에 중 하나를 사용자에게 묻는다. 동의 전에는 설치하거나 지침을 갱신하지 않는다. 나중에를 고르면 `gitifact update --later`를 실행한다. 그 버전의 안내는 24시간 나오지 않고, 더 새 버전이 나오면 바로 다시 나온다. `GITIFACT_NO_UPDATE_CHECK`는 새 버전 조회만 끈다. 프로젝트 기준 비교는 로컬 파일만 읽으므로 계속한다.
 
-업데이트는 프로젝트의 실행 방식을 따른다. 전역 설치본을 쓰면 `npm install -g gitifact@<새 버전>`으로 올린 뒤 `gitifact update`를 실행해 블록의 버전을 갱신한다. npx를 쓰면 `npx --yes gitifact@<새 버전> update`를 실행한다. 프로젝트 의존성으로 관리하면 해당 패키지 관리자로 버전을 올리고 업데이트한 설치본을 실행한다.
+업데이트는 에이전트가 `npm install -g gitifact@<새 버전>`으로 설치한 뒤 `gitifact update`를 실행한다. 프로젝트 의존성으로 관리하면 해당 패키지 관리자로 버전을 올리고 업데이트한 설치본을 실행한다.
 
 설정과 실제 파일, CLI 도움말을 함께 확인해 다음 중 하나의 흐름을 선택한다. 명령이 존재한다는 사실만으로 프로젝트 사용이나 전환이 허용되지는 않는다.
 
@@ -22,7 +22,7 @@ description: 시작할 때 확인할 것, 요구사항으로 남길 요청의
 - **더 이전 형식:** `schemaVersion: 1`(0.4.x)과 workflow-1·prototype-1·init-1 설정은 현재 CLI가 조회·기록하지 않는다. 기존 기록을 삭제하거나 새 형식으로 가장하지 않고, 정식 버전 전 규약이라 전환 도구가 없다고 알린다. 사용자가 원하면 기록을 보존한 채 새로 도입한다.
 - **미도입:** 도입이 허용됐으면 Git 상태와 지침을 확인하고 `init --dry-run`, `init`으로 연결한다. Git 저장소가 없으면 Git 생성 권한을 확인한다. 기존 변경과 staging을 보존한다.
 
-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`으로 알린다. 이때 에이전트가 메시지를 바꿔 대신 커밋하지 않고 사용자에게 알린다.
+init은 `.gitifact/config.json`과 도입 기준선을 만들고, 설정에 CLI 버전(`cli`)과 블록 언어(`language`)를 적는다. 블록에는 버전과 언어가 없고 이 두 값이 기준이다. AGENTS.md 등 에이전트 지침 파일에는 `<!-- GITIFACT:START -->`와 `<!-- GITIFACT:END -->` 사이의 블록을 쓴다. 블록이 AGENTS.md에 들어가고 CLAUDE.md가 없으면 `@AGENTS.md` 한 줄짜리 CLAUDE.md를 함께 만든다. 마커 바깥의 내용은 건드리지 않는다. 요구사항·커밋은 만들지 않는다. 블록은 규칙의 요약이며, 상세 형식은 `gitifact guide show <topic>`으로 읽는다. CLI를 업데이트한 뒤 `update`(또는 `init`)를 실행하면 블록이 새 버전의 문구로 바뀌고 설정의 `cli`가 그 버전으로 올라간다. 프로젝트 기준보다 오래된 CLI는 블록과 `cli`를 바꾸지 않는다. 블록 언어는 설정의 `language`를 따르고(0.8.2 이하에서 만든 블록은 첫 줄의 언어), `--lang ko` 또는 `--lang en`을 지정한 경우에만 바꾸며 설정도 함께 바뀐다. 새 프로젝트는 CLI 언어를 따르고 프로젝트 문서는 기존 언어를 유지한다. `update`는 새 버전 여부와 설치 방법도 알려 주며 설치를 직접 실행하지는 않는다. 갱신 후에는 블록을 다시 읽고 새 버전으로 작업한다. 갱신된 설정과 지침이 커밋·공유되면 다른 팀원은 pull한 뒤 다음 명령에서 프로젝트 기준 안내를 받는다. 업데이트 동의만으로 커밋·푸시하지 않는다. 커밋까지 요청받았을 때만 `update --commit`을 쓴다. 블록 안만 바뀐 지침 파일과 `cli`·`language`만 바뀐 `.gitifact/config.json`을 `chore(gitifact): update project to gitifact v<버전>` 메시지로 그 파일들만 커밋하고, 다른 staging은 그대로 둔다. 블록 밖이나 설정의 다른 항목에도 수정이 있거나 추적하지 않는 파일이거나 Git이 커밋을 거부하면 커밋하지 않고 `commit.reason`으로 알린다. 이때 에이전트가 메시지를 바꿔 대신 커밋하지 않고 사용자에게 알린다.
 
 ## 맥락 읽기