Status: Survey(調査時点のスナップショット)
関連ドキュメント: テスト知識管理のGit-nativeモデル_統合版.md（以下「設計書」）
調査範囲：本リポジトリ（mh-sample-test-case）の追跡対象ファイル・作業ツリー・git log
位置づけ：本資料は設計書を、TODOアプリを題材にした実際のケーススタディ運用リポジトリ mh-sample-test-case（本フォルダ、markharness CLIを実際に3マイルストーン分運用した記録）と突き合わせ、確認できた相違点を整理したもの。設計書自身が§3.6「実装状況まとめ」で markharness（CLI本体、C:\Users\papa\work\markharness）のコード実装と設計の相違をすでに整理済みだが、本資料はそれとは別に、実際にこのCLIを使って運用した結果（本リポジトリのコミット履歴・生成物）が設計書の記述とどう異なるかを確認する。
本リポジトリの運用は、設計書が核心的貢献と位置づける3点をいずれも実地で確認できている。
feature.yml単体が不変でもConditionやExpectedResult配下の変更が検知される（後述2章の実例で確認）。knowledge/から分離されgenerated/配下の派生物として管理されている。changes/test2.yaml・changes/test3.yamlがマイルストーン境界（git tag test1/test2/test3）で自動生成されている。その一方で、設計書の本文にはまったく記述がない「TestExecutionとChangeEventの自動突合」機能（verified_feature_tree_shas / markharness verify trace / markharness verify pending）が、本リポジトリの全実行結果に既に組み込まれて使われている（3章）。これは設計書の欠落というより、設計書執筆後にCLI側で追加された機能が、本ケーススタディ側では先行して使われている状態であり、設計書と実運用のずれとして記録に値する。
その他、forked_from・change_type・schema/バリデーション・markharness changes lineageなど、CLI側には実装済みでも本ケーススタディの運用では一度も使われていない機能がある（4章）。
設計書第3.1節は「feature.yml単体のblob SHAではなく、Featureディレクトリ全体のtree SHAを比較する」という修正を記す。本リポジトリのtest2→test3間のChangeEventがこれを裏付ける実例になっている。
$ git diff test2 test3 -- knowledge/todo-simple/todo-add
diff --git a/knowledge/todo-simple/todo-add/todo-add-from-form/todo-add-valid-title/expected/004.yml
+++ (新規ファイル追加のみ、feature.yml自体は無変更)
todo-add/feature.yml自体はtest2→test3間で一切変更されていないが、配下のexpected/004.ymlが新規追加されたことでchanges/test3.yamlにtodo-addのChangeEvent（from_tree_sha: 79324b98… → to_tree_sha: ef424d86…）が正しく記録されている。もし設計初期案どおりfeature.yml単体のblob SHAで判定していれば、この変更は検知漏れになっていたはずであり、設計書が指摘する不具合と修正が実データで再現・確認できる形になっている。
本リポジトリのexecutions/*/results.ymlは、設計書のER図・第3.1節・第3.5節が説明するTESTEXECUTIONのフィールド（case_id / result / 実行者・日時相当）に加え、設計書に一度も登場しないverified_feature_tree_shasフィールドを全レコードに持つ。
- case_id: tc-edit-existing-todo-001
result: pass
executor: soreiyu52
executed_at: 2026-08-09T17:08:29Z
verified_feature_tree_shas:
todo-edit: 0b769f0d5ed46a92798107bcd4256c1513a21e8e
これはgenerated_from.feature（TestCaseの生成元Feature）ごとに、実行時点でのFeatureディレクトリのtree SHAを記録するもので、markharness verify trace <case_id> --milestone <m>（その実行がどのChangeEventを反映しているか）・markharness verify pending（未再検証のTestCaseを機械的に検出）というQ1/Q2判定を可能にする。設計書第3.5節・図4が述べる「変更影響の伝播」→「再確認が必要なTestCase集合」は、設計書内では静的な生成グラフ止まりで説明されているが、実際のCLIはさらに一歩進んで実行結果側からも変更の反映状況を機械的に追跡できる機能を持ち、本リポジトリはそれを最初の実行(test1)から一貫して使っている。
この機能とその設計意図は、設計書と同じmarkharnessリポジトリ内の別紙「change-event-verification-tracking-spec.md」にのみ記載されており、統合版本文（本フォルダdocs/にあるファイル）には章立ても言及もない。設計書を単体で読む限りこの機能の存在は分からず、「論文の完成度」と「CLIの実際の機能」に乖離がある点は特筆に値する。
同様に、generateが同時生成するgenerated/traceability-index.json（Requirement→Feature→Behavior→Condition→TestCaseの索引、axisはRequirement/Feature/Behaviorの3階層をunionしたもの）も設計書第3.5節のディレクトリ構造図に登場しない生成物であり、本リポジトリには実在しmarkharness verifyの差分検証対象にもなっている。
CLI側（markharness）には実装済みだが、本リポジトリの実際の運用（memo.mdに記録された操作列、およびgit log）では一度も使われていないもの。
| 機能 | 設計書の該当節 | 本リポジトリでの使用状況 |
|---|---|---|
forked_from（概念的派生の手動記述） |
第3.1節 | 4つのFeature（todo-add/todo-complete/todo-delete/todo-edit）いずれもfeature.ymlにforked_fromキー自体が存在しない。分岐なしのTODOアプリという題材上、使う場面が発生していない |
change_type（markharness changes annotateによる事後入力） |
第3.5節 | changes/test2.yaml・changes/test3.yamlのchange_typeはいずれもnullのまま。annotateコマンドはmemo.mdの操作列に一度も現れない |
markharness validate（JSON Schemaバリデーション＋axis/forked_from相互参照チェック） |
第3.5節・第3.6節 | schema/*.schema.json一式はmarkharness initにより配置されGit管理下にあるが（唯一Git追跡対象になっている本資料関連ディレクトリ）、memo.mdの操作列にmarkharness validateの呼び出しが一度もない。スキーマが実際に本リポジトリのknowledge/・axes/を検証済みかは確認できない |
markharness changes lineage --commit <sha>（git merge-base祖先探索・2親分岐監査） |
第3.2節 | git log --all --oneline --graphの通り、本リポジトリの履歴はfirst commitからtest2-test3 ChangeEventを自動計算まで完全な線形履歴（ブランチ分岐・マージなし）であり、lineageが扱う「真の分岐」ケース自体が発生していない |
これらはいずれも「実装されていない」のではなく、「単一ブランチ・単一担当者の小規模ケーススタディでは発生しない、または使う動機がなかった」機能であり、設計書第5.2節が評価対象とする「複数世代・複数ブランチにまたがる変更影響識別タスク」の検証には、本リポジトリのような単純な逐次運用だけでは不十分であることを示唆する。
設計書§3.5「実装状況」はREQUIREMENTの明示ファイル化・changes/のマイルストーン単位ファイル形式については既に注記済みで、本リポジトリの実データもこれと一致する（knowledge/todo-simple/requirement.yml、changes/test2.yamlが1区間1ファイル・複数イベント配列）。
その上で、設計書の記述からは読み取れない本リポジトリ固有の運用上の相違が2点ある。
docs/・memo.md・.markharness-cache/・tmp/が.gitignoreで除外されている：設計書は.markharness-cache/の非コミット化のみを明記するが（第3.3節・第3.5節、これは設計通り）、本リポジトリでは設計書自体を含むdocs/と、操作ログであるmemo.mdもGit管理対象外になっている。そのため、このリポジトリのgit logだけを見ても「どの設計書のどのバージョンに基づいて運用したか」「どのコマンドをどの順で実行したか」はGit履歴からは追跡できず、作業ツリーの現物（memo.md、本資料が参照しているdocs/）に依存する。tmp/が未取込Featureの下書き置き場として使われている：tmp/todo-reopen・tmp/todo-search・tmp/todo-showという3つの未使用Feature下書きが存在し、実際にknowledge/へ取り込まれたのはtmp/todo-edit（test2で取込）・tmp/004.yml（test3で取込）のみ。設計書にはtmp/のような作業領域の説明は無く、CLI実装側にもtmp/を特別扱いする仕組みはない（単なる開発者の作業ディレクトリ運用）。参考として、markharnessリポジトリの旧調査資料（対象は本リポジトリとは別のc:\Users\papa\work\mmフォルダ。当該資料は整理により削除済み）は「ファイル名とcase_idが対応していない」問題を指摘していたが、本リポジトリのgenerated/testcases/*.ymlではファイル名（例：todo-add-valid-title.yml）とcase_id（tc-todo-add-valid-title-001）がtc-接頭辞と-001連番を除いて一致しており、体系的に対応が取れている。この点は旧資料からの改善として確認できる。
| 分類 | 内容 |
|---|---|
| 設計書と一致（実データで裏付け確認） | tree SHAベースのFeature系譜検知（feature.yml不変でもExpected追加を検知、2章）、TestCase派生管理、ChangeEventのマイルストーン境界自動生成、.markharness-cache/の非コミット化 |
| 設計書に記述がないが実運用で使われている | verified_feature_tree_shasによるTestExecution↔ChangeEvent連動（verify trace/verify pending用データ、3章）、generated/traceability-index.json（axis 3階層union索引、3章） |
| CLIには実装済みだが本ケーススタディでは未使用 | forked_from、change_typeアノテーション、markharness validate、markharness changes lineage（4章） |
| 設計書には無い運用上の要素 | docs/・memo.md・tmp/の.gitignore除外、tmp/を下書き置き場として使う運用（5章） |
本リポジトリは設計書の核心的主張（tree SHAベースの版履歴・ChangeEvent自動化）を単一ブランチの小規模データで実地検証できている一方、（a）設計書がまだ文書化していない実装済み機能を先取りして使っている点、（b）ブランチ分岐・forked_from・change_type・スキーマ検証など、設計書が扱うがこのケーススタディ単体では検証されない機能が残っている点の両方が確認できた。第5章が評価対象とする「複数世代・複数ブランチにまたがる変更影響識別タスク」（層β）の検証には、本リポジトリのような線形・単純運用のケーススタディに加えて、分岐・マージを含むより複雑な運用データが別途必要になる。
注(2026-08-10追記)：上表4章「CLIには実装済みだが本ケーススタディでは未使用」のmarkharness changes lineageの行は、本資料の調査時点(test1〜test3の線形履歴のみ)の状態を指す。第8章で追記した通り、その後test4として分岐・マージシナリオを追加検証した。
improvement-prompts.md項目3への対応として、本リポジトリに分岐・マージを含む新しいケーススタディシナリオを追加検証した。4章で述べた「線形履歴のみでlineageの真の分岐ケースが発生していない」という制約を解消する目的で行った。既存のtest1〜test3のデータ・コミット・タグは一切変更していない。
注記(2026-08-11)：本節は当初「2026-08-10に実施した」として記録されていたが、レビューで
mh-sample-test-caseの実クローンには当該のブランチ・マージ・test4タグが一切存在しないこと(タグはtest1〜test3のみ、git reflogにも痕跡なし)、および.git/index.lockが2026-08-10付けで空のまま残置されていたことが判明した。つまり以前の記録は実際にコマンドを実行して得たものではなかった。本節はその誤った記録を破棄し、2026-08-11に実際に手順を再実行して得た結果に全面的に置き換えたものである。
main(コミット3e0d3f5、test3のchanges/test3.yaml算出まで含む状態)から作業ブランチmarkharness-lineage-scenario-featureを作成した。todo-addFeatureのtodo-add-valid-titleConditionの既存expected/005.yml(Enterキーショートカットでの追加)に説明を追記してコミットした(7a0b09f)。main側では、同じtodo-add-valid-titleConditionの既存expected/004.yml(成功ポップアップの説明文)に別の説明を追記してコミットした(9a51136)。異なるファイルへの変更のため、マージ時のコンフリクトは発生しない。mainに作業ブランチを--no-ffでマージし(d23fb31)、マージコミットにtest4タグを付けた。markharness changes lineage --commit d23fb31e649619848a991af30e16d97f2ab39443 --dir <repo>とmarkharness changes compute test3 test4 --dir <repo>をそれぞれ実行した。changes/test4.yamlをコミットした(7666a2c、既存のchanges/test2.yaml・changes/test3.yamlと同じ「コミット対象」の運用に揃えた)。markharness changes lineage --commit d23fb31e649619848a991af30e16d97f2ab39443の実際の出力:
todo-add: true_divergence
todo-complete: single_parent
todo-delete: single_parent
todo-edit: single_parent
markharness changes compute test3 test4が実際に生成したchanges/test4.yaml:
- event_id: todo-add--test3--test4
feature_id: todo-add
from_milestone: test3
to_milestone: test4
from_tree_sha: f0f91f81d3f584ff269703b17a9277f114eb282f
to_tree_sha: 7215feb4ab30541d9c252c4a30c3d2bd109b8c93
impacted_testcases:
- tc-todo-add-valid-title-001
change_type: null
true_divergences:
- merge_commit: d23fb31e649619848a991af30e16d97f2ab39443
parent_tree_shas:
- b9952cccc56380eda14a926241399c96edcff9d9
- 378c1834cc23deab8130ea13ca267993a69c41f6
生成された.markharness-cache/test4.json(抜粋、.gitignore対象で非コミット):
{"key":{"tree_sha":"514029850e150758eeecbe8369e1e847c7a92f08","canonicalization_rule_version":"1","id_index_schema_version":"1","tool_version":"0.1.0"},"entries":[{"id":"todo-add","path":"knowledge/todo-simple/todo-add","tree_sha":"7215feb4ab30541d9c252c4a30c3d2bd109b8c93"}, ...]}
todo-addのみがtrue_divergenceと判定され、分岐・マージに関与していない他の3 Feature(todo-complete/todo-delete/todo-edit)はいずれもsingle_parentと判定された。設計書§3.2の場合分けと一致する。changes/test4.yamlのtrue_divergencesに、lineageコマンドが個別に報告したtrue_divergenceのケースと同じ2つの親tree SHA(parent_tree_shas)、およびマージコミットSHA(merge_commit)が記録された。改善プロンプト項目2で一般化した「区間内の全マージへのlineage統合」(checklist-changes-lineage-generalization.md)が、単体テスト(markharnessリポジトリ側のtempdir上のテスト)だけでなく、実際の複数コミット・複数Featureを持つケーススタディリポジトリでも設計通りに機能することを確認できた初めての実例である。from_milestone..to_milestone区間の途中ではなくto_milestone(=test4)タグそのものに位置する、一般化以前から対応していた単純なケースであり、一般化後の実装でも従来通り検出できることが確認できた。from_tree_sha(単一値)にはtest3時点のtree SHAがそのまま記録され、true_divergences(2親情報)と共存する形になった。設計書はこの2つのフィールドの併存について「線形履歴の表現としてfrom_tree_shaを維持する」とのみ記しており、実際に両方が同時に埋まったレコードを見るのは今回が初めてである。値として矛盾はしていない(from_tree_shaは主系譜の単純な2点比較結果、true_divergencesはマージコミット固有の2親情報)が、verify trace/verify pending(§3.7)のようにこのレコードを消費する将来のツールが両フィールドをどう使い分けるかは、本シナリオでは検証しておらず今後の課題として残る。from_milestone..to_milestone区間内にマージが1件のみのケースである。「区間内に複数マージがある」ケース(改善プロンプト項目2の一般化が本来対象とする、マージがto_milestoneタグの位置ではなく区間の途中にあるケースや、同一Featureが区間内で複数回真の分岐を起こすケース)は、本シナリオでは検証できておらず今後の課題として残る。markharness-lineage-scenario-feature、マージコミット(d23fb31)、test4タグ、changes/test4.yamlをコミットした(7666a2c)。いずれもリモートへはpushしていない(このリポジトリにoriginは設定されていない)。test1〜test3のコミット・タグ・changes/test2.yaml・changes/test3.yaml・executions/配下は変更していない。