Skip to content

docs: rebuild the guarantee ledger as docs/guarantees/ (guarantee-audit) - #43

Merged
yktsnet merged 1 commit into
mainfrom
docs/guarantees-dir
Nov 11, 2026
Merged

yktsnet merged 1 commit into
mainfrom
docs/guarantees-dir

Conversation

@yktsnet

@yktsnet yktsnet commented Nov 11, 2026

Copy link
Copy Markdown
Owner

1ファイルの docs/guarantees.md を、guarantee-audit の形の docs/guarantees/ へ組み直す。新しい約束もテストも足していない。

変更内容

  • docs/guarantees/README.md に目的・分け方・書き方・引き方・運用・Files・Gaps を置き、About をやめた(対象範囲は冒頭へ。地位は README の Design Decisions と同格とした)
  • 約束の対象ごとに8ファイルへ分けた: build(走査・トップ・ディレクトリとファイルのページ・画像と HTML)・links(生成したページのリンク・Markdown 本文のリンク・GitHub の URL・画像の参照)・incremental・config(設定の検証)・issues・plugins(拡張のインターフェース)・publish・sessions(例の拡張)。旧 §1 は対象が多いので build / links / incremental / config に分け、旧 §3 の設定の誤りは config へ、旧 §4 の check_every_hours の検証も config へ寄せた
  • 宣言の箇条と要約の表を表の1行に畳み、1行に約束1つへ分けた(76の宣言・80の表の行 → 150行)。10行以上のファイルは ## の見出しで分けた(plugins.md だけ6行で見出しなし)
  • 同じ名前の test_links_are_relative_and_resolve には置き場(tests/test_build.py / tests/test_example_sessions.py)を添えた
  • 旧本文の「台帳 1 と同じ規則」の番号参照は「Markdown 本文と同じ規則」に直した
  • README.md・README.en.md のリンクと、.claude/skills/pr-workflow/SKILL.md の台帳のパスと更新の手順を新しい置き場へ直した。issues/done/ は記録なので残した
  • 旧 docs/guarantees.md を消した

Gaps へ移したもの(テストを読んで裏付けが無かった部分)

  • 直下にファイルが無いディレクトリに案内文を出すこと: test_readme_on_directory_page は案内文が出ない側しか見ていない
  • --incremental の入力のうち、置き場所・アカウント・本体のコード・[scan.repos] 以外の設定・Issue の一覧: テストは HEAD・他のリポ・[scan.repos]・拡張の targets の変化だけ
  • check_every_hours の起動のずれの見込みが5分であること: テストは1分短い場合と直後しか見ていない
  • waits の表示がリンクであること: テストは waits on <リポ> #<番号> の文字しか見ていない。表の行は「文字として出る」に改めた
  • 旧 Gaps の 20,000 ファイルの件はそのまま残した

内部実装として台帳に載せないテスト

なし。全テストが表に出ており、表に挙げたテスト名はすべて実在する(照合済み)。

迷った仕分け

  • 旧台帳で要約の表にだけあった約束([scan.repos] の値が表でなければ止める、[scan.repos] を変えると --incremental も作り直す、セッションのページの左に件数を出さない)は、テストがあるので表の行にした。件数を出さない理由(使い回しのため)は書いていない
  • issues.md の「Issue のページのリンクは相対パス」と sessions.md の同じ約束は、links.md に集めず各ファイルに残した。テストもページも別で、落ちたテストの名前から行が1つに決まるため
  • error:・非0・public/ を作らない、の3つは「ビルドの前に止まる」1つの約束として1行のままにした
  • --incremental の約束は build から incremental.md へ切り出した。publish も使うため、別の対象とした

確認

  • nix develop -c pytest -q: 89 passed
  • 校正(jp-proofreader)と組み立ての点検(md-reviewer)を通した

1ファイルの docs/guarantees.md を、約束の対象ごとのファイルと README からなる docs/guarantees/ へ組み直す。宣言と要約の表を表の1行に畳み、1行に約束1つへ分ける。テストで裏付けの無い部分は Gaps へ移す。台帳を指すリンクと pr-workflow の手順を新しい置き場へ直す。
@yktsnet
yktsnet merged commit 5e7118e into main Nov 11, 2026
3 checks passed
@yktsnet
yktsnet deleted the docs/guarantees-dir branch November 11, 2026 10:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant