f0rge schema v1 (frozen)

Single source of truth for every .forge/ format. No byte changes without a schema-version bump in the contract (f0rge --skill).

0. Global rules

• Identity: id is uuid4, lowercase, dashes kept. Never changes.
• Timestamps: RFC3339 UTC with fractional seconds: 2025-09-08T02:00:00.123456Z (parser accepts plain ...00Z too). Lexicographic order == chronological order. Field names: created, updated, closed, due (milestones: YYYY-MM-DD or full RFC3339).
• Files: YAML frontmatter between --- fences + markdown body. No frontmatter (except ci.env, labels.md, milestones.md, scripts) = error. Unknown frontmatter field = warning, never error. Missing required field = error naming file + field.
• Parse caps (SEC-01): file > 256 KiB rejected; nesting depth > 32 rejected; > 100 YAML aliases rejected. All before full parse.
• Numbers: derived, never stored. Issue/PR number = 1-based rank of id in total order (created, id) at list time.
• Archive: state: archived + move to .forge/archive/<type>/<uuid>/. Nothing is deleted. Indexes skip archived by default.
• CI verdict vocabulary: pass | fail | running | cancelled.
• Gitignored: .forge/ci/runs/, .forge/releases/out/ only.
• States: issue open|in-progress|closed|archived; pr open|closed|merged (+ draft: bool); task status: todo|doing|blocked|done; milestone open|closed.
• address: issue <N> | task|pr <uuid> | milestone|label <name> | wiki <path>

1. Layout (OUTLINE §5)

.forge/issues/<uuid>/issue.md + comments/<uuid>.md
.forge/prs/<uuid>/pr.md + patch.diff + comments/<uuid>.md + reviews/<uuid>.md
.forge/tasks/<uuid>.md
.forge/labels.md · milestones.md
.forge/wiki/ (index derived: tree + first H1)
.forge/ci/ci.env + steps/NN_name.sh + runs/<ts>/summary.md
.forge/releases/<version>.md + build/ + out/ (ignored)
.forge/merges/<ts>.md
.forge/archive/<type>/<uuid>/

2. Entities

issue — .forge/issues/<uuid>/issue.md

Required: id, title, state, created. Optional: labels: [str] ([]), assignees: [str] ([]), milestone: str, updated. Body = issue text. Golden: spec/fixtures/issue.md.

issue-comment — comments/<uuid>.md

Required: id, created. Optional: author. Body = comment. Golden: spec/fixtures/issue-comment.md.

pr — .forge/prs/<uuid>/pr.md

Required: id, title, state, base, head, created. Optional: draft: bool (false), issues: [uuid] ([]), ci: verdict, updated. Body = description; sidecar patch.diff. Golden: spec/fixtures/pr.md.

pr-review — reviews/<uuid>.md

Required: id, created. Optional: author, state: approved|changes-requested|commented. Body = review text. Golden: spec/fixtures/pr-review.md.

task — .forge/tasks/<uuid>.md

Required: id, title, status, created. Optional: assignee, updated, closed. Column derived from status (todo|doing|blocked|done). Create: --title T [--body B] [--column C] (default todo); body = markdown after frontmatter. Golden: spec/fixtures/task.md.

label — entries in .forge/labels.md (YAML list)

Required: name. Optional: color, description. Golden: spec/fixtures/labels.md.

milestone — entries in .forge/milestones.md (YAML list)

Required: name. Optional: state (open), due, description. Golden: spec/fixtures/milestones.md.

release — .forge/releases/<version>.md

Required: version, created. Optional: title, sha (HEAD short sha at create time; absent on old records). Body = notes. Verbs: create <ver> --notes <file|-> [--title S], install [ver|main] [--dry-run] (list/view unchanged). Golden: spec/fixtures/release.md.

merge-record — .forge/merges/<ts>.md

Required: pr (uuid), verdict: pass|fail, created. Optional: applied: bool (false), resolved: [str] ([]). Body = notes. Golden: spec/fixtures/merge-record.md. Gate only: CI-gates patch in scratch worktree; never touches main/branches; prints conflicts, never resolves; you integrate (ff) + delete branch.

ci-env — .forge/ci/ci.env (YAML mapping, no fences)

Known: runner: local|docker (default local). Any extra KEY: value string knob allowed, never secret. Golden: spec/fixtures/ci-env.

ci-step — .forge/ci/steps/NN_name.sh

Executable script, filename order, exit 0 = step pass, first nonzero exit = run fail. Golden: spec/fixtures/ci-step.sh.

ci-run — .forge/ci/runs/<ts>/summary.md (gitignored)

Required: run, verdict, created. Optional: steps: [{name, exit, duration_ms}]. Golden: spec/fixtures/ci-run.md.

3. Derived indexes (pure, deterministic)

• Issue/PR numbers: sort (created, id), 1-based rank.
• Kanban: group task ids by status (todo|doing|blocked|done).
• Wiki index: walk tree, title = first # H1 else filename.
• --json (compact, fixed order): issue number,title,state,labels,assignees,milestone,body,createdAt,comments (comments = count); pr number,title,state,base,head,draft, databaseId,status,conclusion,createdAt (databaseId = uuid, status/conclusion from ci); wiki list path,title,size; release create/view version,title,created,body,status, release list version,title,created,status (status: built|none, derived from out/<ver>/).

4. Procedures (wiki, release, init)

wiki — files are the API; index derived, never stored

• wiki get <path>, wiki put <path> - (stdin only), wiki list.
• Index: walk tree (symlinks skipped, files > 256 KiB skipped), index title = first H1, else filename; sorted by path.
• Paths are wiki-relative: absolute, ., .. rejected (escapes wiki, exit 1); missing page (not found, exit 1); directories are not pages (is a directory, exit 1).
• Put/get are exact bytes; stdin capped at 256 KiB.
• wiki pages are plain files in git; edit or remove with rm + git (git is the undo log); 'never delete' governs entity history (issues/prs/tasks), not doc files.

release — notes are truth, build is a side effect

• release create <ver> --notes <file|-> [--title <t>] writes releases/<ver>.md (upsert: last write wins), then runs the build.
• <ver> becomes <ver>.md; separators/escapes rejected (escapes releases, exit 1); missing --notes is usage (exit 2).
• Build: executable scripts in releases/build/ (filename order, argv-only, VERSION/OUT env) run at the <ver> tag in a temp worktree, else against the current tree; outputs land in releases/out/<ver>/ (gitignored); sha256 of artifacts is appended to the notes body. Empty build dir = no-op.
• release list order: (created, version); release view <ver> prints the notes body. No delete verb (nothing is deleted).
• Install (local machine op; never forge state, never CI): release install (latest record), release install <ver> (pinned: record must exist else no such release: <ver>, exit 2), release install main (current checkout). Resolve record sha > git tag > current checkout for pin + stage releases/build/<ver>/; if CWD repo-root install.sh exists run it argv-only as ./install.sh <ver> (F0RGE_RELEASE_SHA env carries the pin; it owns placement); else if CWD Cargo.toml exists cargo install --locked from the resolved tree; else no installer for this project (install.sh or Cargo.toml) (exit 1). --dry-run prints the path it would take (one line) without touching the machine.
• Build artifact: CI copies target/release/f0rge to releases/build/<ver>/f0rge per release record (gitignored, never committed); status: built|none still derives from out/<ver>/.

init — bootstrap skeleton, idempotent

• init [dir] (default cwd) creates dirs issues prs tasks wiki/docs wiki/research wiki/experiments ci/steps releases/build merges, files labels.md ([]), milestones.md ([]), ci/ci.env (runner: local), and appends any missing .gitignore lines (.forge/ci/runs/, .forge/releases/out/, *.tmp).
• Idempotent: existing files kept (never clobbered), gitignore lines never duplicated. No git requirement (works in any dir).