gitifact 0.7.0 → 0.8.0

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

@@ -1,52 +1,71 @@
-# Feature design format
+---
+title: Feature design format
+description: Design axes and splitting files, frontmatter, diagrams, revisions
+---
+
+A feature's design is the set of files under its `design/` folder. It explains the structure and processing that implement the feature's requirements. Each file covers one view (axis) of the design.
+
+## Axes and splitting files
+
+| File | Covers |
+| :--- | :--- |
+| `overview.md` (required) | Scope and approach, components and boundaries, open questions |
+| `data.md` | Storage format, data structures and relations, caches, state and lifetime |
+| `interface.md` | Commands, APIs and contracts, inputs and outputs, boundaries with other modules |
+| `ui.md` | Screen layout and routes, display flow, interaction |
+| `errors.md` | Error handling, input validation, recovery, what is tested |
 
-A feature's `design.md` explains the shared structure and processing that implement its requirements.
+A feature with any design must have `overview.md`. The other axes are recommended; create only the ones you need. If the feature is small and each view fits in a paragraph or two, keep everything in `overview.md`. Move a view into its own axis file when it grows to several sections or changes independently of the others. Do not create empty axis files or files that only fill in a template. If a view outside the table is needed, add a file with a lowercase, digits and hyphens slug.
+
+Do not write the same content in two files. `overview.md` does not repeat the details of other axes; it is enough that a reader can tell which axis files exist.
 
 ## File structure
 
-The CLI writes the owning specification's S-ID as `id` in frontmatter. List reference documents in frontmatter `sources`. Each entry has a `title`, either a `path` (a relative path from this file to a `.md` wiki page) or a `url` (http/https), and an optional `note`. Use this list to manage references instead of scattering them throughout the body. The browser shows them as cards on the design tab; it does not fetch external titles or previews.
+Create a file with `gitifact specs new design <feature>/<axis> --title "<title>" --description "<one line>"`. The CLI issues a D- ID, sets `order` to the highest in the folder plus 10, and adds `draft: true`. After writing the body, delete the `draft: true` line and check with `gitifact check`. Do not make up IDs.
 
 ```markdown
 ---
-id: S-actual-owning-specification-ID
+id: D-value-issued-by-the-CLI
+title: Post storage
+description: Storage format for posts and attachments and the cleanup order on delete
+order: 20
+requirements:
+  - R-actual-related-requirement
 sources:
-  - title: Architecture
-    path: ../../wiki/architecture.md
+  - id: I-actual-instruction-followed
     note: Layers and dependency direction
-  - title: Library documentation
+  - title: Library docs
     url: https://example.test/docs
 ---
 
-# Posts design
-
-## Overview
-Scope and implementation approach.
-
-## Processing flow
-<!-- gitifact-ref: R-actual-related-requirement-ID -->
-The main flow from input to result.
+Posts are ...
 ```
 
-This is a structural example. Fill it with known project details before saving; do not save placeholder IDs or instructional sentences. Reference actual requirements at section level with `<!-- gitifact-ref: R-ID, R-ID -->`. Examples inside code fences do not count as references. The browser resolves body links such as `../../assets/flow.png` to their destinations.
+The IDs and sentences above illustrate the structure. Fill in real values; do not save the example as is.
 
-Follow `gitifact docs writing` for prose, diagrams, and alerts. Use the project's language.
+- **`title`, `description`:** Required, one line each. Do not repeat the title as a `#` heading in the body. Body sections start at `##` and contain no gitifact comments.
+- **`order`:** Order the files so the feature is easy to follow. Overview comes first; the default after it is data → interface → ui → errors. Values must not repeat within the folder.
+- **`requirements`:** Only the R- IDs this file actually explains. Several design files may point to the same requirement. Do not copy every requirement of the feature into every file.
+- **`sources`:** Documents this file is based on. Documents in the repository are listed by ID as `{id, note?}`; external material as `{title, url, note?}`. The browser shows this list as source cards. It does not fetch titles or previews of external pages.
 
-## Saving and references
+Relative links in the body (such as `../../../assets/flow.png`) are relative to this file, and the browser links them to their targets. Relations between documents are expressed in frontmatter, not links.
 
-Use `set-design` in `spec save` operations (type, feature, title, body, and optional sources array). A single request may include create, add, and set-design to save both files. The CLI writes frontmatter; it does not create empty designs automatically. Obtain new R-IDs from the result, then add references to the relevant design sections in a follow-up save. Never invent IDs in advance. Delete a design with `delete-design` (type and feature).
+## Writing the body
 
-For `MISSING_DESIGN_REFERENCE` warnings from working/save, check the source and whether the requirement was deleted or moved, then correct it where appropriate. `MISSING_LINK_TARGET` means a sources path or body link has no target. Do not claim a link is valid while ignoring the warning.
+Follow `gitifact guide show writing` for style. The body describes the current structure and behavior. Separate what is decided, what was observed in the implementation, and what is proposed.
 
-## When to write a design
+A design keeps no decision table. A choice among options goes into a record with its context and the alternatives considered, and the body states only the result as a rule (`gitifact guide show records`). Before changing a design, read how its decisions went with `gitifact records list --doc <D-ID>` so an option already passed over is not proposed again. How it changed, when, and the old approach go into records too, not the body.
 
-Prepare requirements.md and design.md together for a new feature by default. Follow a request for requirements only, and do not generate designs for every existing specification just because they are missing. Designs are optional in the format; no staged approval process is required. Ask about consequential uncertainties only. tasks.md is not supported yet.
+For diagrams, follow `gitifact guide show writing` for choosing the kind and drawing it, and place each in the file for the axis it explains. Each axis has kinds that suit it: `erDiagram` and a `flowchart` of cache or read flows for data, a `sequenceDiagram` of requests between components for interface, a `stateDiagram-v2` of screen states for ui, and failure and recovery flows for errors.
 
-## Sections
+Before writing a design, read the instructions for the area of work from the AGENTS.md index and list the ones you followed in `sources`. Do not repeat what an instruction already says; a design holds only what is particular to this feature. Instructions do not point at designs, so the relation is written in this one direction only. If the design conflicts with an instruction, agree with the user on whether to change the instruction first.
 
-Use only the sections needed from this outline: Overview / Structure and data / Processing flow / Error handling and validation / Key design decisions / Open questions. Distinguish agreements, observations, and proposals. Explain consequential alternatives and reasons for the choice. A list of decisions does not replace an implementation explanation. Omit open questions if there are none.
+## When to write one
 
-Before writing a design, read the wiki's architecture and rules pages and list the ones followed in `sources`. If the design conflicts with wiki guidance, agree with the user whether to revise that guidance first.
+When shaping a new feature, write requirements and design together by default. If the user asks only for requirements, do that, and do not bulk-create designs for existing features that have none. Do not enforce step-by-step approval; ask only about important unknowns.
 
 ## Revisions
 
-Read the existing design and related requirements before changing affected sections. Maintain the current design instead of rewriting the entire document each time; Git preserves earlier versions. Review the design when requirements change. A design-only change does not require a manufactured requirements change.
+Before revising, read the feature's design files and the related requirements, and change only the files affected. Rewrite the sentences that changed instead of appending “previously we …” sentences. How it changed goes into a record, and Git keeps the old text. When a decision changes, change the rule in the body and write a new record. When a requirement changes, review the designs that point to it ("Referenced by" in `gitifact specs show <R-ID>`); when only the design changes, do not force changes to requirements.
+
+When splitting a large file into axes or merging files, only move sentences; do not edit content in the same commit. After moving, check that every sentence of the old file is present in the new files. Keep IDs when moving files, and make sure the `requirements` of a deleted file moved to the remaining files. A commit that only moves sentences needs no record.

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

@@ -0,0 +1,81 @@
+---
+title: Project instruction format
+description: The format of per-task instruction folders, the AGENTS.md index, how instructions relate to specs, assets and commits
+---
+
+Project instructions hold how work is done in this project: architecture rules, decisions that span features, writing style, verification steps. Requirements say what to build and a design says how one feature is built; instructions say how the project works regardless of feature. Keep feature behavior in specs and do not repeat it in instructions.
+
+## Folders and files
+
+An instruction is a folder, `.gitifact/instructions/<name>/`. Names use lowercase letters, digits and hyphens, up to 80 characters. The folder's `index.md` is the instruction document; split long content into files under `references/` in the same folder, and link to them from `index.md` with relative links.
+
+```text
+.gitifact/instructions/
+  cli-architecture/
+    index.md                 instruction document (I-)
+    references/
+      checklist.md           a long list
+  verification/
+    index.md
+```
+
+Create new instructions with the CLI. It issues an `I-` ID, fills in the frontmatter and adds `draft: true`. Write the body, remove that line and check with `gitifact check`.
+
+```text
+gitifact instructions new code-review --title "Code review" --description "What to check in a review and how to report it. Use when reviewing a change."
+```
+
+```markdown
+---
+id: I-value-issued-by-the-cli
+title: Code review
+description: What to check in a review and how to report it. Use when reviewing a change.
+---
+
+Rules and reasons. Long lists go in [references/checklist.md](references/checklist.md).
+```
+
+The ID and sentences above only show the structure. The frontmatter of `index.md` has only `id`, `title` and `description`, all required. The `description` says both what the instruction holds and for which work to read it. Do not repeat the title as a `#` heading in the body; start body sections at `##` and do not add gitifact comments. Reference files are not parsed as documents, so they have no frontmatter or ID and any format. Follow `gitifact guide show writing` for the prose.
+
+Edit existing instructions directly. To rename one, move the folder and keep the ID; to delete one, delete the folder. If a design's `sources` still names a deleted instruction, fix that design too or `check` fails. An instruction folder without `index.md` is an `INSTRUCTION_INDEX_REQUIRED` problem.
+
+## The AGENTS.md index
+
+Agents read AGENTS.md in every session. Write, briefly and outside the GITIFACT block, which instruction to read for which work. The CLI rewrites the block, so do not put the index inside it.
+
+```markdown
+## Instructions by task
+
+- When changing CLI code: `.gitifact/instructions/cli-architecture/index.md`
+- Before verifying or committing a change: `.gitifact/instructions/verification/index.md`
+```
+
+When you create, rename or delete an instruction, update the index too. Short facts every session needs belong in AGENTS.md; content needed only for certain work belongs in an instruction.
+
+## Relation to specs
+
+Instructions do not point at specs. An instruction is knowledge that spans features; tied to one feature's spec, it goes stale when that spec changes. The only direction is a design listing the instructions it followed in `sources` as `{id: I-…}`. Markdown in an instruction folder that links under `.gitifact/spec/` is an `INSTRUCTION_SPEC_LINK` problem. A path pattern describing the storage format inside a code block is not a link.
+
+Write links between instructions and to assets relative to the file, for example `../verification/index.md` or `../../assets/diagrams/flow.png`. `check` and `changes list` report a link without a target as a `MISSING_LINK_TARGET` warning.
+
+## Decisions
+
+An instruction keeps no decision table or decision log file of its own. Structure and technology choices that span features are written in the instruction body as rules; their context and the alternatives considered go into records that name the instruction (`gitifact guide show records`). Before changing an instruction, read how its decisions went with `gitifact records list --doc <I-ID>`. When a decision changes, change the rule in the body and write a new record.
+
+When an instruction is created or widened, find the same content in designs with `gitifact specs list --q` and remove it there. Add the instruction to those designs' `sources`, and record the move in one record (`docs` naming the instruction and the designs changed).
+
+## Assets
+
+Keep images, PDFs and other non-Markdown files inside the instruction folder or under `.gitifact/assets/`: files one instruction uses go in its folder, files several documents share go in assets. For assets, the recommended extensions are png, jpg, gif, webp, svg and pdf, and the recommended size is at most 1 MB per file and 50 MB in total. Larger files can still be committed; `check` and `changes list` report them with `ASSET_SIZE`, `ASSET_EXTENSION` and `ASSETS_TOTAL_SIZE` warnings. Assets files no document references are reported with `UNREFERENCED_ASSET`.
+
+## Commits
+
+A change to an instruction is a change to its `index.md`; a record names it by its I- ID in `docs`. Other files of the folder may be listed in `paths` and committed along with it; a change to them alone needs no record (`gitifact guide show commit`).
+
+## Agents
+
+- 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.
+- `gitifact instructions list` shows whether AGENTS.md exists and how many files each instruction folder holds. Read an instruction's `index.md` with `instructions show <name>` and a file of its folder with `instructions show <name> --file references/<file>`.
+- If a request conflicts with an instruction, say so before proceeding. Whether to change the instruction is the user's call.
+- When a new rule or decision spans features, suggest recording it in an instruction. If the user agrees, edit an existing instruction or create one with `gitifact instructions new`, and update the AGENTS.md index.
+- The 0.7 wiki (`.gitifact/wiki/`) became instructions in 0.8.0. `check` reports any page left there as `WIKI_REMOVED`. Follow `gitifact guide show migrate` to move them.

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

@@ -0,0 +1,139 @@
+---
+title: Migrating a 0.7 project
+description: Steps, checks and the migration commit for moving a schemaVersion 2 project to the 0.8.0 document format
+---
+
+When the user asks to move a 0.7 project (`schemaVersion: 2` in `.gitifact/config.json`) to the 0.8.0 document format (schemaVersion 3), follow these steps. The CLI has no conversion command, so the agent reads the old files and writes the new structure itself. Finish with a report in the form of the "Report" section.
+
+In this guide, `gitifact` means the way to run the CLI that printed it (0.8.0 or later). Do not use a 0.7.x CLI. The 0.8.0 CLI refuses to read a schemaVersion 2 project, so read the files directly until step 3 changes the configuration.
+
+## 1. Before you start
+
+- `git status` must be clean. If there are uncommitted changes or staged files, stop and tell the user.
+- If an **open branch** changed `.gitifact/` in the old format, tell the user to merge it before the migration and ask whether to merge or continue. Merging an old-format branch after the migration mixes the two formats, and `gitifact check` fails.
+- The migration ends in a single commit. Confirm that you may commit. When possible, work on a new branch and merge after verification.
+- Section 3 of this guide describes the whole new format. If a detail is unclear, run `gitifact init` and `gitifact specs new feature|requirement|design|instruction …` in an empty Git repository outside the project to see the skeletons the CLI writes, and check them with `gitifact check`.
+
+## 2. Reading the old format
+
+| Old file | Format |
+| :--- | :--- |
+| `.gitifact/spec/<feature>/requirements.md` | Frontmatter `id: S-…`, first body line `# Feature title`. A paragraph between `# title` and the first `## ` is the feature's introduction. Each requirement is a `## Requirement title` followed by a `<!-- gitifact-req: R-… -->` line; everything below it up to the next `## ` (outside code blocks) is the requirement body |
+| `.gitifact/spec/<feature>/design.md` (when present) | Frontmatter `id` (the feature's S-) and optional `sources` (`title`, `path` or `url`, `note`). First body line `# Design title`; sections carry `<!-- gitifact-ref: R-…[, R-…] -->` |
+| `.gitifact/spec/<feature>/history.jsonl` | One line per reason: `{"id":"H-…","requirements":[R-…],"designs":[S-…]?,"documents":[W-…]?,"reason":"…"}` |
+| `.gitifact/wiki/**/*.md` | Frontmatter `id: W-…`, first body line `# Page title` |
+| `.gitifact/wiki/history.jsonl` | The same reason lines, usually with `documents` |
+
+Count before you start: features (`requirements.md` files), requirements (`gitifact-req` comments), designs (`design.md` files) and wiki pages. Section 4 compares against these counts.
+
+## 3. Moving to the new structure
+
+Every structural fact lives in frontmatter only. Bodies carry no `#` title and no `<!-- gitifact-` comments (code blocks excepted). `title` (200 characters) and `description` (300 characters) are single lines and both are required.
+
+1. **Configuration:** set `schemaVersion` in `.gitifact/config.json` to 3. Leave `baseline` as it is.
+2. **Features:** create `.gitifact/spec/<feature>/index.md`.
+   ```markdown
+   ---
+   id: S-…            # the old requirements.md id, unchanged
+   title: Feature title    # the old # title, unchanged
+   description: One line saying what this feature is
+   ---
+
+   (The old introduction paragraph if there is one; otherwise one or two sentences on the feature's scope and purpose. A body is required.)
+   ```
+3. **Requirements:** create `.gitifact/spec/<feature>/requirements/<slug>.md` for each requirement. The slug names the title in lowercase English letters, digits and hyphens (80 characters at most). `order` follows the old file: 10, 20, 30… Move the old requirement body **without changing a character** (keep the `###` subheadings); only trim blank lines at its start and end.
+   ```markdown
+   ---
+   id: R-…
+   title: Requirement title
+   description: One line saying what it requires
+   order: 10
+   ---
+
+   (the old body, unchanged)
+   ```
+4. **Designs:** for each feature with an old design.md, run `gitifact specs new design <feature>/overview --title "<old design title>" --description "<one line>"` to get a D- ID. Replace the body of the `design/overview.md` it created with the old design body (without its first line `# Design title`) and remove the `draft: true` line. Then:
+   - Remove the old `<!-- gitifact-ref: … -->` lines and list every R- ID they named, without duplicates, in the frontmatter `requirements`.
+   - Move old `sources`: a `path` becomes `- id: W-…` for the wiki page it points to (with its `note`, if any); a `url` becomes `- title: …` / `url: …`. The W- becomes the I- of the instruction that page moves to in step 5.
+   - Leave the rest of the body unchanged. Keep the `order: 10` that `specs new` wrote. Do not split a design into files per concern (data, interface, ui, errors, …) in the migration commit. Move it as one overview so the moved body can be compared, and split it afterwards in a separate commit following `gitifact guide show design`.
+   - The frontmatter ends up like this. Sources in the new format have no `title`, so the old title of a wiki source is dropped.
+     ```markdown
+     ---
+     id: D-…
+     title: Old design title
+     description: One line
+     order: 10
+     requirements:
+       - R-…
+       - R-…
+     sources:
+       - id: I-…
+         note: the old note (if any)
+       - title: Outside document title
+         url: https://…
+     ---
+     ```
+5. **Wiki → instructions:** in 0.8.0 the wiki became project instructions (`gitifact guide show instructions`). `check` refuses pages left in `.gitifact/wiki/` with `WIKI_REMOVED`, so move every page into an instruction folder. Before moving, show the user a table of which page becomes which file of which instruction and get their confirmation. If the user changes the grouping, follow it.
+
+   | Old location | New location |
+   | :--- | :--- |
+   | `wiki/README.md` (policy and entry page) | If it is still the default policy `init` wrote (decision records collected under `adr/`), delete it without moving. If the project rewrote it, move it like a root page to the `index.md` of instruction `overview`. Whether its wiki rules move to AGENTS.md is decided in section 6 |
+   | Root page `wiki/<name>.md` | `index.md` of instruction `<name>`. Upper-case names become lower case (`ARCHITECTURE.md` → `architecture`) |
+   | Top-level folder `wiki/<folder>/` | Instruction `<folder>`. The folder's `README.md`, if any, becomes `index.md`; the other pages become `references/<path inside the folder>` |
+   | Folder with the same name as a root page | One instruction; the root page is `index.md` |
+
+   - For each instruction, run `gitifact instructions new <name> --title "<title>" --description "<one line>"` to get an I- ID. The title is the old title of the page that becomes `index.md`. For a folder without such a page, name the topic the folder holds (for example `handbook` → Team handbook). The description says what the instruction holds and for which work to read it.
+   - For the page that becomes `index.md`, drop the first body line `# Title` and move the rest unchanged: replace the body `specs new` wrote with it and remove the `draft: true` line. If a folder has no page to become `index.md`, write one line per reference file in the body, with its old title and a link.
+   - Pages moved to references keep the old file as it is (including the `# Title` line); remove only the frontmatter and the blank line after it, so the file starts with `# Title`. Reference files are not parsed as documents and have no ID.
+   - Move images and other non-Markdown files from the wiki folder into the instruction folder that uses them.
+   - Instructions cannot point at specs (`INSTRUCTION_SPEC_LINK`). In the moved files, reduce links under `.gitifact/spec/` from `[text](path)` to their text. Other relative links are fixed for the new location in step 6.
+   - Design `sources` that named a wiki page W- in step 4 now name the I- of the instruction that page moved to. If a design ends up naming the same instruction twice, merge the two and join the notes with `; `.
+   - The old W- IDs disappear from documents and stay only in the reasons of 0.7 commits.
+   - Do not turn the wiki's decision record (ADR) pages into record files or regroup instructions in the migration commit. Move bodies unchanged so they can be compared, and polish them in a separate commit after the migration.
+6. **Relative links:** requirements and designs moved, so fix relative links in document bodies that point to the old `requirements.md` or `design.md`, or that break because a file moved (requirement and design bodies are now one folder deeper). Point links to wiki pages at the instruction files the pages moved to, and fix links inside moved instruction files for their new location. Do not edit bodies beyond fixing links.
+7. **Reasons:** do not move the reasons in the old history.jsonl files. They stay in the 0.7 commits and remain visible in the history (`records list --doc`, the browser) after the migration. Reasons for changes from 0.8.0 on are kept in records (`gitifact guide show records`). The migration commit gets no records; it is hidden from the history.
+8. **Delete the old files:** remove every `.gitifact/spec/<feature>/requirements.md`, `design.md`, `history.jsonl` and the whole `.gitifact/wiki/` folder (including `wiki/history.jsonl`), once step 5 has moved every page, with a plain file deletion. Do not use `git rm`: it stages the deletion and the commit in section 5 refuses existing staging. If something is staged, unstage it with `git restore --staged <path>`.
+
+The mechanical parts (splitting files, moving wiki pages) may be done with a one-off script. Keep the script outside the project and never commit it. Write slugs, descriptions and feature bodies yourself after reading the content. Every feature, requirement and instruction needs a description, which makes this the largest part of the migration (68 for a project with 18 features, 45 requirements and 5 instructions). A description should let a reader recognize in one line of a list what the document requires or covers; do not repeat the title, condense the user story or the first paragraph instead.
+
+**Allowed exceptions:** normally only the CLI issues IDs and committed reasons are never edited. For this migration only, existing S- and R- IDs are copied over. Never invent IDs (designs get their D- and instructions their I- from `specs new`).
+
+## 4. Checks
+
+1. `gitifact check` must report no problems. Fix anything it reports.
+2. Compare with the counts from section 2: features = number of `index.md`, requirements, designs (`design/overview.md` per feature), wiki pages (the `index.md` and reference files in the step 5 table together). Count documents with `gitifact specs list --format json` and `gitifact instructions list --format json`.
+3. Check that every old ID is present. Collect old IDs from `git grep -ohE '(S|R)-[a-z2-7]{10}' HEAD -- .gitifact` at their definitions (frontmatter `id`, `gitifact-req` comments) and new IDs from `documents[].id` of `gitifact specs list --format json`. No `.gitifact/wiki/` or `history.jsonl` file may remain and no design `sources` may name a W-.
+4. The last lines of `gitifact changes list` must include `Document check: no problems`. Its other output is expected at this point: the old format does not parse as documents, so every document shows as `created`. New documents need no record. None of this blocks the commit.
+
+## 5. Commit
+
+Write JSON to the input path that `gitifact changes list` reports and run `gitifact changes commit --file <that path>`, first with `--dry-run`. `paths` is every path in `git status --porcelain --untracked-files=all` (`.gitifact/cache/` excludes itself and does not appear). Quote the user's request for the migration and the commit in `evidence`.
+
+```json
+{
+  "paths": ["<every changed, new or deleted path: .gitifact/config.json, the new documents, the deleted old files>"],
+  "message": "chore(gitifact): migrate to the 0.8.0 document format",
+  "authorization": { "basis": "user-request", "evidence": "<the user's words asking for the migration and commit>" },
+  "migration": true
+}
+```
+
+- `migration: true` adds the `Gitifact-Migration: 0.8.0` trailer. That commit becomes the history boundary: activity before it stays visible in the viewer, and the commit itself does not appear as activity.
+- Add no records; the 0.7 reasons are read from the 0.7 commits.
+- The deleted old files must be in `paths`; without them the CLI refuses the commit.
+
+## 6. After the migration
+
+- Refresh the GITIFACT block in the agent instruction files with `gitifact update`. If project instructions outside the block (AGENTS.md, CLAUDE.md, …) mention old commands such as `spec working`, `spec save`, `spec commit` or `docs <topic>`, ask the user whether to replace them with the new ones (`list`, `show` and `new` of `specs`, `instructions` and `records`, `check`, `changes list`·`commit`, `guide show`) in a separate commit.
+- If the old index of the 0.7.x browser exists at `<git common dir>/gitifact/` (usually `.git/gitifact/`), tell the user it can be deleted. 0.8.0 does not use it; leave the deletion to the user.
+- The 0.8.0 cache lives in `.gitifact/cache/` and keeps itself out of Git. The first query reads the history from the start and may take a few seconds.
+- If the wiki README moved to instruction `overview` holds rules for running the wiki (what goes where), agree with the user whether to move them to AGENTS.md or another instruction. Then write the instruction index outside the GITIFACT block of AGENTS.md: one line per instruction saying for which work to read it ("The AGENTS.md index" in `gitifact guide show instructions`). Ask the user whether to record this in a commit separate from the migration.
+- Turning the ADRs moved to references into records (`gitifact guide show records`) while leaving only the rules to keep in the instruction body, and regrouping instructions, are agreed with the user and done in a separate commit. The migration commit is hidden, so records written in that later commit are the ones the history shows.
+- The migration commit leaves bodies as they were, so instructions or specification bodies may still describe the old format (`requirements.md`, `spec save`, …) or refer to the wiki. Report where, and agree with the user on fixing them in a separate commit.
+
+## 7. Report
+
+- Moved counts: features, requirements, designs, wiki pages (with the old counts), and the table of instructions the wiki pages moved to
+- The `check` result and the comparison result
+- Relative links fixed, anything not moved or that needed a judgment call
+- The commit hash (if committed) and what remains (old commands in instructions, the old index)

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

@@ -0,0 +1,82 @@
+---
+title: Record format
+description: When to write a record, the file and its sections, from draft to commit, and how to read records
+---
+
+A record keeps why a document looks the way it does. A document body holds only what is valid now, so the context and the options chosen that the body cannot explain go into records. A committed record is never edited. When a decision changes, write a new record; reading one document's records in order shows how its decisions went.
+
+## When to write one
+
+| Case | Record |
+| :--- | :--- |
+| Changing or removing what an existing requirement, design or instruction says | Write one. The old text is gone, so a record is the only place for the context |
+| Choosing one of several options while creating or changing something | Write one. Alternatives considered do not go into the document body |
+| Simply adding a new requirement | None. The user story is the reason |
+| A document changed as a consequence of another decision | None of its own. Add the document to that decision's `docs` |
+| A typo or wording fix | None |
+
+Record a decision when it is made. Written at commit time from memory, context such as the alternatives considered gets lost. One task with several decisions has several records.
+
+## The file
+
+A record is one file, `.gitifact/records/<yyyymmdd>/<DR-ID>.md`. Create it with the CLI, which issues the ID and writes it in the folder of today's date (created on the first record of the day) with the required sections and `draft: true`.
+
+```text
+gitifact records new --title "30-day retention of deleted posts" --docs R-…,D-…
+```
+
+```markdown
+---
+id: DR-value-issued-by-the-cli
+title: 30-day retention of deleted posts
+docs:
+  - R-actual-changed-requirement
+  - D-actual-changed-design
+---
+
+## Context
+
+About 20 requests a month ask to restore a post deleted by mistake.
+
+## Decision
+
+A deleted post stays in the trash for 30 days; a cleanup job then removes it for good.
+
+## Alternatives considered
+
+- Remove at once (restore requests cannot be met)
+- Keep forever (storage keeps growing)
+```
+
+The ID and sentences above only show the structure. Fill in the sections, then remove the `draft: true` line; a record that still has it cannot be committed.
+
+- **`title`:** one line of at most 80 characters. It names the record on the browser's decision records page and in `records list --doc`. Write a short noun phrase naming what was decided (for example `500-character section limit`, `Removal of decision tables from documents`, `One decision per commit recommended`), not a sentence, not only the topic (`500-character section limit`, not `Section length`); the reason goes in a section.
+- **`docs`:** IDs of the documents the record explains, including ones it deletes. Documents changed as a consequence go here too.
+- **Author and time:** not in the file. They are read from the commit that added the record.
+
+| Section | Required | Content |
+| :--- | :--- | :--- |
+| Context | Yes | What called for the decision: the problem, request or constraint |
+| Decision | Yes | What was decided |
+| Alternatives considered | No | Options actually weighed and not chosen, with why |
+
+The body holds only these `##` sections. Headings may be in English (`## Context`) or Korean (`## 맥락`). A section not in the list, or one that appears twice, is a `check` problem. Write alternatives only when options were actually weighed; do not make them up. When there were none, as in most requirement changes, leave the section out.
+
+## Length
+
+Write two to five sentences each for the context and the decision. The context says what the problem was (what was seen and any numbers measured), who asked for what, and the constraints to keep. The decision says what was decided, how far it applies and its exceptions. Do not pad a section with what nothing supports. A section over 500 characters is a `check` problem (`RECORD_SECTION_TOO_LONG`). List alternatives one per line with why they were not chosen in brackets. Leave out the history, the measuring and the old ways. API fields, implementation steps and test notes stay in the design or the commit, not the record. If a longer explanation is needed, put it in the design or instruction body and keep only the gist in the record. Follow `gitifact guide show writing` for the prose.
+
+## Committing
+
+Commit a record with the documents it explains by listing its file in the commit input's `paths` (`gitifact guide show commit`). One decision per commit is the default, together with its documents, code and tests. When a file spans two decisions, commit both records together. `changes list` shows which documents each record explains and which documents two records explain.
+
+A committed record is not edited or deleted. If it is, `check` reports `RECORD_ALTERED` and the commit is refused; restore it from HEAD and write the changed decision as a new record.
+
+## Reading
+
+| Command | When |
+| :--- | :--- |
+| `gitifact records list --doc <ID>` | Before changing a document, read how its decisions went: each record's title and sections with its commit |
+| `gitifact records show <DR-ID>` | One record as written and the commit that added it |
+
+Do not read or grep every file under `.gitifact/records/`. Records are placed only by day and ID, so gathering them by document means reading them all; `records list --doc` finds them through the cache's index.

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

@@ -1,62 +1,99 @@
-# Markdown specification format
+---
+title: Requirement format
+description: Feature and requirement files, frontmatter, user stories and acceptance criteria, creating, editing and moving
+---
+
+A feature is one folder, `.gitifact/spec/<feature>/`. The feature introduction is `index.md`, each requirement is its own `requirements/<slug>.md`, and the design is the files under `design/` (`gitifact guide show design`). Why a document changed is kept in records (`.gitifact/records/`, `gitifact guide show records`).
+
+```text
+.gitifact/spec/posts/
+  index.md                 feature introduction (S-)
+  requirements/
+    create.md              one requirement (R-)
+    delete.md
+  design/
+    overview.md            design (D-)
+```
+
+## Creating
 
-Each feature has a `.gitifact/spec/<feature>/requirements.md` containing its requirements. Its design is in `design.md` in the same folder (`gitifact docs design`); reasons for changes are in `history.jsonl`.
+Create files through the CLI. It issues the ID, fills in the frontmatter and writes a body skeleton.
+
+```text
+gitifact specs new feature posts --title "Posts" --description "Writing, editing and deleting posts"
+gitifact specs new requirement posts/create --title "Create a post" --description "An author saves a post with a title and body"
+```
 
-## Files and IDs
+A new file carries `draft: true`. Fill in the body, remove that line and run `gitifact check`. While the line remains, `check` and `changes commit` fail. Do not invent IDs or copy another document's ID.
 
-Use S-IDs and R-IDs exactly as issued by the CLI. They have the form `S-<random>` and `R-<random>`, with ten lowercase base32 characters. Do not put feature names into R-IDs or invent example IDs for actual saves. Files start with frontmatter; each requirement heading is immediately followed by its ID comment.
+## File structure
 
 ```markdown
 ---
-id: S-issued-by-the-CLI
+id: R-issued-by-the-CLI
+title: Create a post
+description: An author saves a post with a title and body
+order: 10
 ---
 
-# Posts
-
-## Create a post
-<!-- gitifact-req: R-issued-by-the-CLI -->
-
 As a post author, I want to save a title and body so that I can return to my writing later.
 
 ### Acceptance criteria
 
 1. Condition: The user requests a save with an empty title.
-   Expected behavior: The system asks for a title and does not save the post.
+   Expected: The system asks for a title and does not save the post.
 ```
 
-These IDs illustrate the structure and are not valid input. Frontmatter contains only `id`. Use one top-level heading (`#`) and `##` for requirements. Do not add other gitifact comments to the body. Links to other documents are relative to this file, such as `../../wiki/architecture.md` or `../../assets/flow.png`. The browser resolves them to their destinations. `spec working` reports missing targets as `MISSING_LINK_TARGET`.
+These IDs and sentences illustrate the structure and are not valid input.
 
-## Saving
+- **`id`:** issued by the CLI. Features use `S-`, requirements `R-`, followed by ten lowercase base32 characters. It stays the same when the file moves or its title changes.
+- **`title` and `description`:** required, one line each. Do not repeat the title as a `#` heading in the body. Write the description so that the list (`specs list`) tells what the document is without opening it.
+- **`order`:** requirements only. Number them in the order of the feature's use; two in one feature may not share a number. `specs new` uses the folder's highest value plus 10, leaving room to insert between.
+- **Body:** required. Do not use a `#` heading or gitifact comments (`<!-- gitifact-… -->`). The body of a feature's `index.md` states in a paragraph or two what the feature is and where it ends.
 
-Use the stamp from `spec working` to prepare this JSON, write it to the returned `inputs.save` path, and run `spec save --file <that-path>`. The CLI removes the input file on success. On failure, the file remains; correct it and retry.
+Put no other keys in the frontmatter. Relations between documents are expressed by a design's `requirements` and `sources`; the folder decides which feature a requirement belongs to.
 
-```json
-{
-  "expected": "actual stamp from working",
-  "operations": [
-    { "type": "create", "feature": "posts", "title": "Posts" },
-    { "type": "add", "feature": "posts", "title": "Create a post", "body": "As a post author, I want to save a title and body so that I can return to my writing later.\n\n### Acceptance criteria\n\n1. Condition: The user requests a save with an empty title.\n   Expected behavior: The system asks for a title and does not save the post." },
-    { "type": "set-design", "feature": "posts", "title": "Posts design", "body": "## Overview\n\nAgreed approach and scope.\n\n## Structure and data\n\nComponents and storage needed for implementation." }
-  ]
-}
-```
+Links to other documents are relative to this file (from a requirement to an asset: `../../../assets/flow.png`). The browser opens their destinations. `check` and `changes list` report a missing target as a `MISSING_LINK_TARGET` warning. Warnings do not block a commit.
+
+## Reading
 
-The command group is `gitifact spec`. Use `update` with id, title, and body for an existing requirement; `move` with id and feature to move one; and `rename-spec` with id and title to rename a specification. Pass actual R-IDs or S-IDs obtained from a query. Dedicated requirement deletion and feature-folder renaming commands are not available. Do not invent commands or migration procedures for unsupported operations.
+| Command | When |
+| :--- | :--- |
+| `gitifact specs list [--feature <feature>]` | IDs, titles and descriptions of features, requirements and designs, without bodies |
+| `gitifact specs list --uncovered` | Requirements no design covers. `--without-design` finds features without a design, `--draft` documents still marked draft |
+| `gitifact specs list --changed-since <date\|commit>` | Documents changed since then. Combine with `--author` and `--sort updated` |
+| `gitifact specs list --q <query>` | Finding text in bodies that titles and descriptions do not mention |
+| `gitifact specs show <ID…>` | The source of the chosen documents and the designs that point to them. `--ref <commit>` shows them as of that commit |
+| `gitifact records list --doc <ID>` | Why a document changed over time, with its records and commits |
 
-Include designs in the same request with `set-design` (type, feature, title, body, and optional sources). Read `gitifact docs design` for design rules and `gitifact docs wiki` for wiki pages and assets.
+Choose with the list's conditions, then `show` only the documents you need. A list also gives only the columns you ask for (`--fields id,title`) or JSON (`--format json`). This reads far less than grepping or opening every file.
 
-Follow `gitifact docs writing` for prose. Its style rules do not replace the user-story structure and condition/expected-behavior format below. Write project content in the project's language; the language of these instructions does not change it.
+## Editing, moving and deleting
+
+Edit the files directly; there is no save command. Afterwards run `gitifact check` to verify format and references.
+
+| Task | How |
+| :--- | :--- |
+| Change content | Edit `title`, `description` and the body. Keep the ID |
+| Move to another feature | Move the file into that feature's `requirements/`, keep the ID, and adjust `order` to its place there |
+| Rename the slug | Rename the file only. ID and content stay |
+| Delete | Delete the file. Remove its ID from the `requirements` of any design that pointed to it, or `check` fails |
+| Rename a feature (folder) | Move the folder. The S- ID in `index.md` stays |
+
+Do not duplicate a document under a new ID when moving or renaming it, and do not reuse a deleted ID. When a requirement changes, review the designs that point to it (“Referenced by” in `specs show <R-ID>`).
 
 ## Grouping features
 
-Group requirements into cohesive features that mean something to users. Do not reproduce code modules or DDD layers. Check whether an existing specification is a suitable home first. Keep a requirement's ID when its title or folder changes, including when correcting a misplaced requirement. Do not duplicate it under a new ID. Use the feature name as the specification title without a suffix such as “requirements.”
+Group requirements into cohesive features that mean something to users. Do not reproduce code modules or DDD layers. Before creating a feature, check whether an existing one is a suitable home. Use the feature name as its title without a suffix such as “requirements.” Slugs and folder names use lowercase letters, digits and hyphens.
 
 ## User stories and acceptance criteria
 
 Start each requirement with a user story: one or two sentences explaining who wants what and why. The default pattern is “As a [role], I want [goal] so that [reason],” expressed naturally in the project's language. Use an actual user or operator of the product. Do not copy the post author in this example, or a Gitifact user, into an unrelated product.
 
-Follow the story with an acceptance-criteria heading and numbered condition/expected-behavior pairs, in the project's language. Do not substitute paths, IDs, or storage conventions for user goals. Put additional agreed constraints in a scope-and-constraints section and implementation details in the design. Base roles, goals, and reasons on the conversation and verified context. Do not invent motives to fill the template; ask only for information needed to settle the meaning.
+Follow the story with an acceptance-criteria heading (`###`) and numbered condition/expected pairs, in the project's language. Do not substitute paths, IDs or storage conventions for user goals. Put additional agreed constraints in a scope-and-constraints section and implementation details in the design. Base roles, goals and reasons on the conversation and verified context. Do not invent motives to fill the template; ask only for information needed to settle the meaning.
+
+Apply this to new requirements and those being revised for the current request. Preserve existing IDs, agreed constraints and the meaning of acceptance criteria. Do not rewrite unrelated requirements in bulk. When done, check that the story states a role, goal and reason, and that its criteria determine success or failure. The CLI does not enforce particular sentences or validate user intent.
 
-Apply this to new requirements and those being revised for the current request. Preserve existing IDs, agreed constraints, and the meaning of acceptance criteria. Do not rewrite unrelated requirements in bulk. Before saving, check that the story states a role, goal, and reason, and that its criteria determine success or failure. The CLI does not enforce particular sentences or validate user intent.
+Follow `gitifact guide show writing` for prose. Its style rules do not replace the user-story pattern and the condition/expected format above. Write project content in the project's language; the language of these instructions does not change it.
 
-Refine specification drafts during the conversation. Do not record a reason or event for every intermediate edit. While changing code and tests, bring requirements into line with the final agreement.
+Refine the files during the conversation. When an existing requirement changes or one of several options is chosen, write a draft record then (`gitifact guide show records`). Simply adding a requirement needs no record. While changing code and tests, bring requirements into line with the final agreement.