03 Repository Contract

File contracts

A check is possible only where a contract exists. Below is what the pack considers correct, and how each part is verified.

README.md

Item	Rule	Rule id
Title	one H1, under 60 characters	readme.h1
Summary	a paragraph right after the title: what it is, for whom	readme.summary
Badges	3–8: CI, release, license, runtime	readme.badges
Banner	an image above the first section, with alt text	assets.readme-banner
Table of contents	required once the file passes 200 lines	readme.toc
Installation	a section named Installation or Установка	readme.install
Usage	a section named Usage or Быстрый старт	readme.usage
License	a section named License or Лицензия	readme.license
Code	every fence carries a language	readme.code-fence

AGENTS.md

Item	Why
Copy-paste commands	the agent must not guess the syntax
A verification section	how to prove the work is done
A prohibitions section	what not to do, and why
A traps table	the symptom that identifies each trap

CHANGELOG.md

# Changelog

All notable changes to this project are documented here. The format is
[Keep a Changelog](https://keepachangelog.com/en/2.0.0/) 2.0.0, and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.1.0] - 2026-10-20

### Added

- Something a user can see.

[Unreleased]: https://github.com/owner/repo/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/owner/repo/compare/v1.0.0...v1.1.0

Six types: Added, Changed, Deprecated, Removed, Fixed, Security. Dates are ISO. Newer versions sit above older ones. Unreleased stays on top.

wiki/wiki.json

The manifest sets order and navigation. A file missing from the manifest is an error: the page exists but cannot be found.

{
  "repo": "owner/name",
  "branch": "main",
  "title": "Project name",
  "footer": "MIT",
  "groups": [
    {"title": "Start", "pages": ["Home.md", "01-Install.md"]},
    {"title": "Русский", "pages": ["Home.ru.md"], "labels": {"Home.ru.md": "Home (RU)"}}
  ]
}

Images

Rule	Rule id
The repository has an assets/ directory with an image	assets.no-directory
The README references at least one image	assets.readme-banner
Every referenced file exists	assets.missing-file
The social preview is PNG/JPG/GIF	assets.svg-social
The social preview is under 1 MB	assets.social-size
The social preview is at least 640×320, ideally 1280×640	assets.social-dimensions
No image over plain http://	md.image-http

What doc does

Group	Rules
Text	doc.bom, doc.crlf, doc.final-newline, doc.tab-indent
Structure	md.h1, md.heading-skip, md.fence
Tables	md.table
Links	md.link-local, md.link-anchor, md.link-dir
Table of contents	md.toc
Markup	md.alert, md.image-alt, md.image-http, md.hard-break
Privacy	privacy.secret, privacy.abs-path, privacy.email

A file carrying <!-- ghagent: template --> is exempt from link checks: a template contains unresolved placeholders on purpose.

The rule that matters most

If a rule examined zero objects it is not passed. The report names it in a coverage.skipped line, and an empty tree produces doc.no-text-files. A check that checked nothing is more dangerous than no check: it creates confidence.

Next

• Wiki workflow.
• Platform traps.