markharness

0001: Scale back the Version DAG claim to “ChangeEvent model” wording (Option A)

Status

Accepted

Background

docs/git-native-model-for-test-knowledge-management.md positioned a persistent graph of version nodes/edges with derived_from (Version DAG) as a core contribution (§1.1 Figure 1, §1.2 RQ1, §3.4 Figure 3, etc.).

Meanwhile, in the CLI implementation the ChangeEvent struct (src/changes.rs) has no derived_from field; what is actually persisted is only from_tree_sha/to_tree_sha (a linear diff between two milestones) and true_divergences (audit information for two-parent merges). An independent persistent DAG with version nodes/edges is not implemented (P0 finding from the external evaluation review as of 2026-08-12).

To resolve this discrepancy, the following two options were considered.

Decision

Option A was adopted.

Rationale

Impact / Conditions for future reconsideration

Addendum (2026-08-12): Response to improvement prompt item 11, the “merely a git diff/log wrapper” concern

Background of item 11

As a result of Option A scaling back the Version DAG claim to the ChangeEvent model, the external review raised a new concern that “the paper appears to merely wrap git diff/git log.” Upon checking the implementation (src/id_cache.rs), it was confirmed that an already-implemented algorithmic mechanism exists that differs from a simple path-based git diff/git log –follow.

The three points selected as the core to emphasize

  1. Path-independent ID resolution: because a Feature’s id is read from the id: field of feature.yml rather than from a directory name or path, the same Feature can be tracked even after directory rename/relocation, without relying on Git’s path tracking (git log --follow) (id_cache.rs lines 10–22, 84–97).
  2. Directory-level tree SHA comparison: because the comparison target is the tree SHA of the entire Feature directory rather than the blob SHA of feature.yml itself, changes to only Condition/ExpectedResult can be detected without going through feature.yml.
  3. A content-addressed id-resolution cache: the cache key consists of the tree SHA of knowledge/ plus the versions of the rules/schema/tools, adopting the same design philosophy as Git’s commit-graph auxiliary cache (§3.3).

All three of these points have been verified in the existing implementation (src/id_cache.rs); no new implementation was done.

Chosen vocabulary and rationale

The phrase “theoretical core” was avoided in favor of “core design mechanism” / “algorithmic core.” Reason: the ingenuity described in this section is a combination of known techniques — content addressing (Git’s blob/tree SHA) and ancestor search via git merge-base — not a theoretical result accompanied by formal proof or complexity analysis. Calling it “theoretical” would reintroduce, under different vocabulary, the same kind of overstatement that was corrected for item 1 (Version DAG) and item 2 (asserting an existing TMS).

Where reflected

The description in §1.3 (Contributions) was rewritten into the explicit form of the three points above, adding one sentence contrasting it with path-based history tracking (git diff/git log --follow). The same one-sentence contrast was also added to the introductions of §1.1 (Abstract-equivalent), §3.1 (Structure), and §3.3 (id resolution) respectively (the existing technical descriptions themselves were not changed).