gitifact 0.7.1 → 0.8.1

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

@@ -1,24 +1,28 @@
-# Gitifact workflow
+---
+title: Gitifact workflow
+description: What to check at the start, which requests become requirements, and the final report
+---
 
 The user describes the product and keeps developing. The agent organizes product requirements and connects the final changes at commit time. Do not make users learn recording commands or a separate development methodology.
 
 ## Start and check the format
 
-Check the working path, branch, Git status, and existing staging. Read applicable AGENTS.md and CLAUDE.md files in full. Follow the project's CLI invocation. If none is specified, run `npx --yes gitifact@<version> <command>` with the version at the top of the block. Below, `gitifact` stands for that invocation. npx uses a matching project dependency or downloads the package to the npm cache; no global installation is required.
+Check the working path, branch, Git status, and existing staging. Read applicable AGENTS.md and CLAUDE.md files in full. Follow the project's CLI invocation. If none is specified, use the global `gitifact`. First check that `gitifact --version` matches the version at the top of the block. If the command is missing or the version differs, suggest `npm install -g gitifact@<version>` to the user, and until it is installed, or if they decline, run `npx --yes gitifact@<version> <command>`. Below, `gitifact` stands for the chosen invocation. A computer has only one global version, so do not work on this project with a global command of another version. npx uses a matching project dependency or downloads the package to the npm cache.
 
-Do not skip Gitifact work just because the global command is missing or global installation requires permission. Add a project dependency or install globally only when the user chooses that method. If execution or network access is blocked, request the required approval and explain the cause. `--yes` only suppresses npm's installation prompt; it does not grant execution permissions. Continue available investigation, but do not substitute manual specification saves or commits, or claim completion without running the CLI.
+Do not skip Gitifact work just because the global command is missing or global installation requires permission. A global installation is a suggestion, run only with the user's consent; add a project dependency only when the user chooses that method. If execution or network access is blocked, request the required approval and explain the cause. `--yes` only suppresses npm's installation prompt; it does not grant execution permissions. Continue available investigation, but do not issue document IDs, check documents or commit by hand instead of running the CLI, or claim that work is done without it.
 
 Once per new session, run `gitifact update --check` with the pinned version. This command leaves files, the index, and commits unchanged. If the result is `available`, tell the user the current and new versions and ask whether to update. Do not refresh instructions or switch versions before consent. If declined, keep the pinned version and do not ask again in that session. `unavailable` means the check failed, not that the CLI is up to date. If the check fails or is disabled through `GITIFACT_NO_UPDATE_CHECK`, continue with the pinned version.
 
-Update using the project's chosen method. For npx, run `npx --yes gitifact@<new-version> update` to refresh the version in the block. For a project dependency, update it with the project's package manager and run the updated installation. Global installation instructions apply only when using the global command.
+Update using the project's chosen method. For a global installation, run `npm install -g gitifact@<new-version>` and then `gitifact update` to refresh the version in the block. For npx, run `npx --yes gitifact@<new-version> update`. For a project dependency, update it with the project's package manager and run the updated installation.
 
 Check configuration, actual files, and CLI help to choose the applicable workflow. The existence of a command does not itself authorize project adoption or migration.
 
-- **Current format:** `schemaVersion: 2` in config.json uses `.gitifact/spec/<feature>/requirements.md`, optional `design.md`, `history.jsonl`, `.gitifact/wiki/`, and `.gitifact/assets/`. Follow `gitifact docs spec` and `docs wiki`.
+- **Current format:** `schemaVersion: 3` in config.json uses feature folders (`index.md`, `requirements/` and `design/` under `.gitifact/spec/<feature>/`), instruction folders under `.gitifact/instructions/`, `.gitifact/assets/` and records under `.gitifact/records/`. Follow `gitifact guide show spec`, `design`, `instructions` and `records`. A reason file `.gitifact/history.jsonl` left from 0.8.0 development builds is reported by `check` as `REASONS_FILE_REMOVED`. The 0.7 wiki `.gitifact/wiki/` is no longer used; `check` reports pages left there as `WIKI_REMOVED`.
+- **0.7 format:** `schemaVersion: 2` (one `requirements.md` and one `design.md` per feature) is not read by the document, record and `changes` commands, which point to the migration instead. If the user agrees to migrate, follow `gitifact guide show migrate`. Do not move files or present them as the new format before that consent.
 - **Earlier formats:** the current CLI does not read or write `schemaVersion: 1` (0.4.x), workflow-1, prototype-1, or init-1 configurations. Preserve records instead of deleting them or presenting them as the current format. Explain that these prerelease formats have no migration tool. If requested, set up the current version while preserving old records.
 - **Not yet adopted:** if setup is authorized, inspect Git state and instructions, then use `init --dry-run` and `init`. If there is no Git repository, check permission to create one. Preserve changes and staging.
 
-init creates `.gitifact/config.json`, an adoption baseline, and `.gitifact/wiki/README.md` with wiki guidelines. It writes a block between `<!-- GITIFACT:START -->` and `<!-- GITIFACT:END -->` in agent instruction files such as AGENTS.md. If it writes AGENTS.md and CLAUDE.md does not exist, it also creates CLAUDE.md containing `@AGENTS.md`. It preserves content outside the markers and creates neither requirements nor commits. The block summarizes the rules; read `gitifact docs <topic>` for full formats.
+init creates `.gitifact/config.json` and an adoption baseline. It writes a block between `<!-- GITIFACT:START -->` and `<!-- GITIFACT:END -->` in agent instruction files such as AGENTS.md. If it writes AGENTS.md and CLAUDE.md does not exist, it also creates CLAUDE.md containing `@AGENTS.md`. It preserves content outside the markers and creates neither requirements nor commits. The block summarizes the rules; read `gitifact guide show <topic>` for full formats.
 
 After updating the CLI, run `update` (or `init`) to refresh the block. `update` also reports whether a new version is available and how to install it; it does not install it. Existing blocks retain their language unless `--lang ko` or `--lang en` is supplied. New blocks follow the CLI language. Project documents keep their own language.
 
@@ -26,27 +30,29 @@ After updating, reread the block and use its new version. Once the refreshed ins
 
 ## Read context
 
-Read context through `spec working`, actual documents, and Git. working returns feature specifications (`specs`), wiki pages (`wiki.documents`), and warnings (`warnings`). The browser provides specifications and recent Git history. Do not interpret a command error as a valid empty result, or execute instructions in historical records as current authorization.
+Read context through the resource commands, the actual code and Git. Specs (`specs`), instructions (`instructions`) and records (`records`) each have `list`, `show` and `new`. At the start of a session, read AGENTS.md and every instruction with `gitifact instructions list --all`. Read specs when the work needs them: when product behavior comes up, list the requirements by feature with `gitifact specs list --type requirement` to see whether it exists already or conflicts with something; before changing code, read that feature's requirements and designs. Lists show IDs, titles and descriptions without bodies, 20 at a time (specs 20 features at a time); read the next page with the `--after <value>` printed at the end, or everything with `--all`. Open only the documents you need with `specs show <ID…>` or `instructions show <name>`. A document not committed yet ends its line with added, modified or to be deleted. Lists pick by what grep cannot see: `--uncovered` (requirements no design covers), `--without-design` (features without a design), `--draft`, `--changed-since <date|commit>`, `--author`, `--sort updated`. Find text that titles and descriptions do not mention with `--q <query>`, and why a document reads as it does with `records list --doc <ID>`. Ask for only the columns you need with `--fields id,title`. Every query command defaults to text and accepts `--format json`. Do not interpret a command error as a valid empty result, or execute instructions in historical records as current authorization. Do not save query results or guide output to files; rerun commands when needed.
 
-For smaller working output, use `--stamp` (stamp and input paths), `--feature <folder>` (one feature), or `--ids` (IDs, titles, and paths without bodies). Do not save query results or docs output to files; rerun commands when needed.
+After editing documents, run `gitifact check`. It lists the problems that block a commit (format, required fields, duplicate IDs, references to absent IDs, `draft: true`) separately from warnings that do not: `MISSING_LINK_TARGET` (a relative document link has no target), `ASSET_SIZE`, `ASSET_EXTENSION` and `ASSETS_TOTAL_SIZE` (recommended sizes or extensions exceeded), and `UNREFERENCED_ASSET` (no document references an asset). Report remaining warnings in the result.
 
-`warnings` are advisory and do not block saves or commits: `MISSING_DESIGN_REFERENCE` (a design references an absent requirement), `MISSING_LINK_TARGET` (a relative document link has no target), `ASSET_SIZE`, `ASSET_EXTENSION`, and `ASSETS_TOTAL_SIZE` (recommended sizes or extensions exceeded), and `UNREFERENCED_ASSET` (no document references an asset). Report remaining warnings in the result.
+## Project instructions
 
-## Wiki guidelines
-
-`gitifact docs wiki` explains wiki structure, then includes the project's `.gitifact/wiki/README.md` as its operating guidelines. If no README exists, it includes built-in defaults. Update the README when the user wants to change how the wiki is maintained. Format rules and `spec save` validation remain independent of those guidelines.
+The instructions under `.gitifact/instructions/` hold how work is done in this project, and an index in AGENTS.md, outside the GITIFACT block, says which one to read for which work. Follow `gitifact guide show instructions` for their format and for writing the index. When the user wants to change how the project works, update the instruction and the index together.
 
 ## Temporary files
 
-Write save and commit JSON to `inputs.save` and `inputs.commit` returned by `spec working` (or `spec changes`). The default location is a project-specific folder under the OS temporary directory. If that is unwritable, the fallback is Git-ignored `.gitifact/tmp/`. On success the CLI deletes the input and returns `inputRemoved`. Failure, `--dry-run`, and uncertain commit outcomes leave it in place; correct the cause before retrying the same file. working cleans files older than seven days from this folder. Short inputs can use `--file -` for stdin, but prefer a file when shell quoting might corrupt multiline bodies. Do not keep separate input/output copies in the project.
+Write commit JSON to the input path `gitifact changes list` reports (`inputs.commit` in its JSON). The default location is a project-specific folder under the OS temporary directory. If that is unwritable, the fallback is Git-ignored `.gitifact/tmp/`. After a successful commit the CLI deletes the input and returns `inputRemoved`. Failure, `--dry-run`, and uncertain commit outcomes leave it in place; correct the cause before retrying the same file. `changes list` cleans files older than seven days from this folder. Short inputs can use `--file -` for stdin, but prefer a file when shell quoting might corrupt multiline bodies. Do not keep separate input/output copies in the project.
 
 ## Requests to view records
 
-When the user asks to see requirements, project status, history, or release notes, start `gitifact browser` and share the URL. Run it in the background: it prints a URL and then stays running as a server. Do not wait for it to finish or substitute a chat summary of working JSON. Follow requests to explain specific content. If a server started in this conversation is still running, reuse its URL. Open the default browser only when asked.
+When the user asks to see requirements, project status, history, or release notes, start `gitifact browser` and share the URL. Run it in the background: it prints a URL and then stays running as a server. Do not wait for it to finish or substitute a chat summary of list output. Follow requests to explain specific content. If a server started in this conversation is still running, reuse its URL. Open the default browser only when asked.
+
+## Sending feedback on Gitifact
+
+When the user wants to report a bug in Gitifact itself or suggest an improvement, draft the type (`bug` or `idea`), title and body and show them to the user. Describe what the user ran into and how to reproduce it; include project files, document text or paths only when the user asks. Do not send before the user confirms. Once confirmed, write `{"type": "bug", "title": "…", "body": "…"}` to an input file and run `gitifact feedback --file <path>`. Use `--dry-run` first to show how it will be sent and the environment the CLI appends (versions, OS, Node, storage version). With a signed-in `gh`, the CLI creates the issue under the user's account; otherwise it prints the new-issue page address. Give the address to the user to submit in a browser, and pass on the full body when the output says it was cut.
 
 ## Finish
 
-Briefly report the requirements organized, checks actually performed, whether a commit was made, and remaining limitations. Distinguish saving, committing, approval, implementation, and validation. Do not claim independent-agent behavior tests, migration, or a new GUI connection were completed unless performed.
+Briefly report the requirements organized, checks actually performed, whether a commit was made, and remaining limitations. Distinguish edited documents, a passing check, a commit, implementation, and validation. Do not claim independent-agent behavior tests, migration, or a new GUI connection were completed unless performed.
 
 ## What belongs in requirements
 
@@ -61,12 +67,12 @@ Record desired product behavior and conditions to maintain, not every work instr
 | Make the border a little lighter | Usually a style edit; do not create a requirement every time. |
 | Distinguish selected items with a border | Add to acceptance criteria for selection behavior. |
 
-Keep shared presentation rules in a wiki rules page instead of repeating them per feature. Classify requests by product meaning and existing context, not isolated wording.
+Keep shared presentation rules in a project instruction instead of repeating them per feature. Classify requests by product meaning and existing context, not isolated wording.
 
 ## Working through the conversation
 
 Establish users, desired outcomes, main flows, failure conditions, and product constraints through conversation. Do not repeat answered questions or require a long questionnaire. Ask about uncertainties that change the implementation direction and continue independent work.
 
-Before changing requirements, designs, or code, read the wiki pages relevant to the work under the guidelines in `gitifact docs wiki`. If no such page exists, say so and proceed. Flag requests outside the wiki's scope or contrary to its principles before proceeding.
+Before changing requirements, designs, or code, find the instructions for the area of work in the AGENTS.md index, read them and follow them. If none fits, say so and proceed. Flag requests that conflict with an instruction before proceeding.
 
 In existing projects, document the areas being changed first. Derive all features only when asked. Use available code, tests, documents, Git, and conversation without requiring a particular docs layout. Distinguish observed behavior, user intent, and future proposals. Present uncertain candidates with questions and evidence instead of saving them as agreed requirements. Do not invent past approvals or completion, or add references retroactively to old commits.

package/dist/i18n/en/docs/writing.md

@@ -1,13 +1,16 @@
-# Document style
+---
+title: Document style
+description: Shared style for instructions, requirements, designs and records, body versus records, quotations, alerts and diagrams, removing AI slop
+---
 
-Apply this to wiki pages, requirements, and designs. Use the project's language, independently of the CLI display language. Write direct, declarative prose and descriptive headings. Preserve UI text, quotations, and code.
+Apply this to project instructions, requirements, and designs. Use the project's language, independently of the CLI display language. Write direct, declarative prose and descriptive headings. Preserve UI text, quotations, and code.
 
 ## Prose and structure
 
 - Start with the subject and rule. Explain responsibilities, dependency direction, or conditions directly instead of opening with “This document defines…”
-- Keep one topic per paragraph. Include only the background and reasoning needed to understand the rule.
+- Keep one topic per paragraph and put its point in the first sentence. Aim for three or four sentences per paragraph. When a paragraph runs longer, check whether it holds two topics and split it or move it into a table.
 - Summarize system components and boundaries in architecture overviews; link to detailed rules instead of copying them.
-- Use numbered lists for procedures, tables for comparisons and conditional behavior, and paragraphs for explanations. Avoid excessive headings or tables for short material.
+- Use numbered lists for procedures, tables for comparisons and conditional or case-by-case behavior, diagrams for flows, state transitions and component relations, and paragraphs for explanations. Avoid excessive headings or tables for short material.
 - Use terminology consistently. Prefer familiar words and avoid repeatedly restating terms in another language.
 
 ## Specificity and accuracy
@@ -17,32 +20,60 @@ Apply this to wiki pages, requirements, and designs. Use the project's language,
 - Distinguish current implementation, agreed rules, and proposed changes. Do not describe planned features or unperformed checks as complete.
 - Preserve scope, exceptions, and constraints when shortening prose. Style edits must not alter decisions, ADR statuses or dates, identifiers, commands, or code examples.
 
+## What is current and how it got there
+
+The body states only the behavior and rules that hold now. “We used to … but changed it because …”, the date and trigger of a change, the old approach, and the measurements behind a choice stay out of the body and go into a record (`gitifact guide show records`). Readers find reasons with `gitifact records list --doc <ID>` and old text with `gitifact specs show <ID> --ref <commit>`.
+
+When revising, rewrite the sentences that changed instead of appending sentences about the old behavior. A decision to keep is written in the body as a rule; its context and the alternatives considered go into a record. Designs and instructions keep no decision tables of their own.
+
 ## Quotations and alerts
 
-Use ordinary blockquotes for quotations from documents or people. To call out supplementary information, prerequisites, or cautions, use [GitHub alert syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) when needed.
+Use ordinary blockquotes for quotations from documents or people. Put what the next person would easily miss inside a sentence in [GitHub alert syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
 
-- `NOTE`: supplementary information that is easy to miss
-- `TIP`: optional advice that helps with the task
-- `IMPORTANT`: a prerequisite to know before starting
-- `WARNING`: something to watch for to avoid a problem
-- `CAUTION`: a risk such as data loss
+| Kind | Where it goes | Examples in designs and instructions |
+| :--- | :--- | :--- |
+| `IMPORTANT` | Invariants that must not be broken, prerequisites to know before starting | Source files are never modified; failures are never swallowed |
+| `WARNING` | Conditions whose breach causes a security problem or wrong behavior | Do not widen a route that is open without authentication |
+| `CAUTION` | Risks that are hard to undo, such as data loss | This command deletes records |
+| `NOTE` | Known limits, planned removals, supplementary information that is easy to miss | This case cannot be told apart; this code is removed in the next major version |
+| `TIP` | Optional advice that helps with the task | A command for checking the result |
 
 ```markdown
 > [!IMPORTANT]
 > Start Docker before running integration tests.
 ```
 
-Skip alerts when ordinary prose is sufficient. One or two per document is the default, with more only where needed. Avoid consecutive alerts or nesting them inside lists or quotes. Each alert covers one topic in one or two sentences; give long explanations their own section. Do not convert ordinary quotations wholesale.
+Skip alerts when ordinary prose is sufficient. One or two per file is the norm, with more only where needed. Avoid consecutive alerts or nesting them inside lists or quotes. Each alert covers one topic in one or two sentences; give long explanations their own section. Do not convert ordinary quotations wholesale.
+
+## Diagrams
+
+Add a ` ```mermaid ` fence where a flow, an exchange, states or relations read faster as a picture than as text. Pick the kind that fits the content first.
+
+| Content | Kind |
+| :--- | :--- |
+| A processing flow that branches or joins, decisions | `flowchart` |
+| Requests and responses passed between components in turn | `sequenceDiagram` |
+| The states something goes through and what moves it | `stateDiagram-v2` |
+| Tables or entities of a storage structure and their relations | `erDiagram` |
+| The shape of commit history, such as branches and merges | `gitGraph` |
+| Dependencies and composition of modules or types | `classDiagram`, or groups in a `flowchart` |
+
+Some content does not fit a picture: a sequence that runs in one line is a numbered list, and a mapping from conditions to results is a table.
 
-Use diagrams on the same basis: add a `mermaid` fence where a flow or state transition is easier to understand visually. Do not duplicate the same explanation in prose and a diagram. Designs may use diagrams too; one or two per document is the default.
+- Name boxes with short nouns. Details such as commands, paths and settings go in a table or prose below the diagram.
+- Keep to ten boxes or fewer, and five or fewer side by side. When longer, draw top to bottom (`TD`) or split the diagram.
+- Declare the main flow first and branches after it. Use diamonds only for decisions, with labels of a few words.
+- Group boxes of the same source or module in a `subgraph`. Label edges only with conditions, in two or three words.
+- Do not use colors, `classDef` or `style`; the reader's display mode and palette decide colors.
+- Do not retell in prose what the diagram shows; the prose adds only the conditions and exceptions it leaves out.
 
 ## Remove filler
 
 - Remove stock introductions and conclusions, repetitive summaries, and sentences that merely address the reader.
 - Use emphasis and contrasts such as “What matters is…” or “Not just X, but Y” only when they make a necessary distinction.
 - Remove unsupported adjectives such as “systematic,” “efficient,” “powerful,” and “seamless,” or replace them with specific behavior.
-- Keep obvious explanations, narration of the writing process, and task-completion reports out of the document body. Put necessary change records in history documents.
-- Avoid repeated bold text and warnings. Reserve warnings for conditions that can cause data loss or incorrect execution if missed.
+- Keep obvious explanations, narration of the writing process, and task-completion reports out of the document body. Put how something changed in a record.
+- Avoid repeated bold text and warnings. Emphasize only where “Quotations and alerts” calls for it.
 - After editing, check whether each sentence conveys a rule, fact, reason, or procedure. Delete sentences that add no information.
 
 | Avoid | Write instead |
@@ -51,4 +82,4 @@ Use diagrams on the same basis: add a `mermaid` fence where a flow or state tran
 | Separate concerns clearly to improve maintainability. | The UI handles input and display; the server validates permissions and business rules. |
 | It is important to keep documentation consistent. | Maintain shared rules in one document and link to it elsewhere. |
 
-Apply these principles to user stories and acceptance criteria too. Preserve the story and condition/expected-behavior structure required by `gitifact docs spec`.
+Apply these principles to user stories and acceptance criteria too. Preserve the story and condition/expected-behavior structure required by `gitifact guide show spec`.

package/dist/i18n/ko/block.md

@@ -1,15 +1,14 @@
 ## Gitifact Guide
 
-gitifact v{version} · {language} · 저장 규약 schemaVersion 2
+gitifact v{version} · {language} · 저장 규약 schemaVersion 3
 
-CLI: 기본 실행은 `npx --yes gitifact@{version} <cmd>`다. 아래 `gitifact`는 이 실행 방법을 뜻한다. 프로젝트가 로컬 설치본이나 전역 명령 등 다른 실행 방법을 지정하면 그것을 우선한다.
+제품 동작(요구사항·설계), 지침, 결정기록은 `.gitifact/`에 저장하고 CLI `gitifact`로 관리한다. 프로젝트가 별도 실행 방법을 정했다면 해당 방식을 `gitifact`로 적용한다.
 
-### 시작할 때
+### 세션을 시작할 때
 
-- 전역 설치는 필수가 아니다. 지정 버전의 npx 실행은 같은 버전의 프로젝트 설치본을 사용하고, 없으면 npm 캐시에 받아 실행한다. 실행 권한이나 다운로드가 막히면 필요한 승인을 요청하고 원인을 알린다. CLI 실행 없이 명세 저장·커밋을 대신하거나 완료했다고 보고하지 않는다.
-- 새 세션에서 한 번 `gitifact update --check`로 지정 버전보다 새 버전이 있는지 확인한다. `available`이면 사용자에게 업데이트할지 묻고, 동의한 경우에만 안내된 새 버전으로 `update`를 실행한다. 거절·확인 실패·조회 비활성화 시에는 지정 버전으로 계속하며 같은 세션에서 다시 묻지 않는다. 갱신 후에는 블록을 다시 읽고 새 버전을 사용한다. 커밋·푸시는 별도 권한을 따른다.
-- `gitifact spec working`으로 위키·기능 명세·경고를 읽고 git status와 기존 staging을 확인한다.
-- 이 블록은 요약이다. 상세 형식은 `gitifact docs <topic>`으로 읽고 기억으로 채우지 않는다.
+1. `gitifact --version`이 {version}인지 확인한다. 없거나 다르면 `npm i -g gitifact@{version}` 설치를 제안하고, 그전까지는 `npx --yes gitifact@{version} <cmd>`로 실행한다. 실행이 막히면 승인을 요청한다.
+2. `gitifact update --check`를 1회 실행한다. 새 버전이 있으면 업데이트 여부를 묻고, 동의할 때만 설치 후 `update`를 실행한 뒤 이 블록을 다시 읽는다.
+3. `gitifact instructions list --all`로 지침을 모두 확인하고 git status와 기존 staging 상태를 점검한다.
 
 ### 무엇을 요구사항으로 남기는가
 
@@ -17,32 +16,33 @@ CLI: 기본 실행은 `npx --yes gitifact@{version} <cmd>`다. 아래 `gitifact`
 
 | 요청 | 처리 |
 | --- | --- |
-| 게시물을 삭제할 수 있게 해주세요 | 요구사항으로 정리한다 |
+| 게시물을 삭제할 수 있게 해주세요 | 요구사항으로 등록한다 |
 | 이 내부 함수 이름을 바꿔주세요 | 일반 구현 변경이다 |
 | 지금 푸시해주세요 | 작업 지시다. 등록하지 않는다 |
 | 외부 서비스 없이 동작해야 합니다 | 제품 제약으로 명세에 반영한다 |
 
-### 규칙
-
-- 명세를 저장하기 전에 `gitifact docs spec`을 읽는다. ID는 CLI가 발급한 값만 쓴다.
-- 새 기능은 requirements.md와 design.md를 함께 정리한다(`gitifact docs design`). 요구사항만 요청받으면 따른다.
-- 요구사항·설계·코드를 바꾸기 전에 `gitifact docs wiki`를 확인하고 그 운영 방침에 따라 관련 위키 페이지를 읽는다.
-- 이 프로젝트에 맞게 위키 운영 방식을 바꾸려면 `.gitifact/wiki/README.md`를 `spec save`로 고친다. 그 내용이 `docs wiki`의 운영 방침이 된다.
-- 위키·요구사항·설계 본문을 쓰기 전에 `gitifact docs writing`의 문체를 따른다. 문서는 CLI 표시 언어와 무관하게 프로젝트의 언어로 쓴다.
-- 커밋 요청을 받으면 `gitifact docs commit`을 읽고 명세·이유·코드·테스트를 함께 커밋한다.
-- 자동 기록은 커밋 권한이 아니다. 사용자 요청이나 명시적 프로젝트 정책이 있을 때만 커밋하고 푸시는 별도 요청을 따른다.
-- 불명확한 제품 동작만 질문하고 독립적인 작업은 진행한다. 기존 기능 전체 도출은 요청받았을 때 한다.
-- SELF-CHECK: save·commit 입력을 만들기 전에 해당 docs를 다시 읽고 형식을 대조한다. 확실하지 않으면 추측하지 말고 `gitifact docs <topic>`을 실행한다.
-- save·commit 입력 JSON은 `spec working`이 알려 준 inputs 경로에 쓴다. 성공하면 CLI가 지운다. 조회 결과와 docs 출력은 파일로 저장하지 않고 필요할 때 다시 실행한다.
-- 사용자가 요구사항·프로젝트 현황·변경 이력을 보여 달라고 하면 `gitifact browser`를 백그라운드로 실행하고 출력된 URL을 알려 준다. 채팅 요약으로 대신하지 않는다.
+### 작업할 때
+
+| 상황 | 선행 작업 |
+| --- | --- |
+| 제품 동작 관련 요구 | `specs list --type requirement`로 기존 명세와 충돌 여부를 확인한다 |
+| 코드나 문서 수정 전 | 해당 기능의 요구사항·설계(`specs show <ID>`), 블록 밖 색인이 가리키는 지침, 대상 문서의 결정 흐름(`records list --doc <ID>`)을 확인한다 |
+| 문서 신규 작성 | `guide show spec`(설계는 `design`, 지침은 `instructions`)과 `guide show writing`을 읽는다. ID는 `specs new`·`instructions new`로 발급받고, 수정 후 `gitifact check`로 확인한다 |
+| 기존 문서 수정 또는 대안 결정 | `records new`로 결정기록을 작성한다(`guide show records`) |
+| 커밋을 요청받았을 때 | `guide show commit`을 확인하고, `changes list`가 안내한 파일에 입력을 작성한 뒤 `changes commit`한다 |
+| 기록 조회를 요청받았을 때 | `gitifact browser`를 백그라운드로 실행하고 URL을 안내한다 |
+| Gitifact 버그·개선 제보 | 초안을 사용자에게 확인받고 `gitifact feedback`으로 전송한다 |
+
+### 지킬 것
+
+- 커밋은 사용자 요청이나 프로젝트 정책이 있을 때만 수행하고, 푸시는 별도로 요청받는다. 결정 단위마다 기록·문서·코드·테스트를 함께 커밋하며, 작업을 마치고 커밋하지 않았으면 1회 제안한다.
+- CLI를 실행하지 않고 ID 발급·검사·커밋을 대신하거나 완료로 보고하지 않는다.
+- 새 기능은 요구사항과 설계를 함께 작성하고 문서는 프로젝트 언어로 작성한다. 불명확한 제품 동작만 질문하고 나머지는 진행한다.
+- SELF-CHECK: 이 블록은 요약이다. 문서나 커밋 입력을 만들기 전에 `gitifact guide show <topic>`으로 형식을 다시 확인하고 기억으로 채우지 않는다. 조회 결과는 파일로 저장하지 않는다.
+
 ### 명령
 
-- `docs <topic>`: {topics}
-- `spec working`: 현재 명세·위키 전체, 경고, stamp, 입력 파일 경로 (`--stamp`, `--feature <이름>`, `--ids`)
-- `spec save --file <json|->`: 요구사항·설계·위키 저장
-- `spec commit --file <json|->`: 변경 이유 기록과 커밋을 한 번에
-- `browser`: 읽기 전용 브라우저 서버 실행, URL 출력 후 계속 실행
-- `update [--check | --commit]`: `--check`는 읽기 전용 버전 확인. 옵션 없이는 이 블록을 실행 버전으로 갱신하며 `--commit`은 블록만 바뀐 파일을 고정 메시지로 커밋한다
-- `init`: 처음 도입할 때 설정과 이 블록을 만든다
+- `specs`·`instructions`·`records`: `list`·`show`·`new`. `check`: 전체 검사. `changes list`·`changes commit --file <json> [--dry-run]`
+- `browser`, `feedback`, `update [--check | --commit]`, `init`, `guide list`·`guide show <topic>` ({topics}). 목록은 20개씩 출력되며 끝의 `--after <값>`으로 이어 조회한다(`--all`은 전체). `--fields`, `--format json`을 지원하며 옵션은 `--help`로 확인한다.
 
 ---