Accepted (Stages 0–3 were completed on 2026-08-18. Stage 3 implemented a localhost-only read-only Release Verification Dashboard, Feature History, and frontend assets embedded in the Rust binary). The Verification Plan framing this ADR put at the center is superseded by 0020 and by Change Impact / Release Coverage in markharness-v2-design.md (the Stage 3 dashboard itself is removed by 0022). This ADR remains in effect as the record of Stages 0–3 and of the modular-monolith stance.
docs/Markharness_改善・実装検討_統合設計文書.md (dated 2026-08-17, hereafter “the integrated design document”; the file itself has been deleted, since its adoption decisions were transcribed into this ADR and into verification-plan-canonical-model-design.md — recoverable via git log -- docs/) examined three directions for extending the current markharness design — a Git-native model that treats test knowledge as the primary artifact and TestCase as a derived artifact, as already implemented per Section 2.8 and Chapter 3 of the paper.
The current markharness CLI already implements, within a single Git repository’s knowledge/, automatic milestone-boundary ChangeEvent computation (changes compute) and version-binding of execution evidence (verify trace/verify pending) (Chapter 3 of the paper git-native-model-for-test-knowledge-management.md). On the other hand, PR-scoped (arbitrary base/head) Verification Plan generation, import from external tools, and a GUI are all unstarted.
The primary risk the integrated design document identifies is that pursuing these three directions in parallel without discipline would lead to: (a) the import/normalize feature becoming the public face of the product, making it look like it has shrunk into a “version-aware middleware”; (b) re-implementing TestCase CRUD; and (c) the GUI acquiring its own status model that diverges from the Domain Engine. This ADR decides the order and boundaries in which these three directions are pursued.
Markharness turns a change into a reviewable verification plan. Git remains the source of truth.
The competitive axis is not the number of features such as dashboards, RBAC, or SSO, but the speed and quality of answering “for this change, what is sufficient to test?” This sentence is treated as the primary source of truth to reference when updating external-facing copy such as the README.
Extend the existing changes compute (milestone-boundary) so that an arbitrary PR base/head pair is treated as a first-class version range, proceeding in the following order. The rationale for this ordering is the dependency that a stable canonical model is the input the Plan needs, and the Plan is what makes the GUI a meaningful read model (Chapter 8 of the integrated design document).
| Stage | Scope | Exit Criteria |
|---|---|---|
| Stage 0 | Fix the current domain model and terminology in an ADR/schema document. Turn a fixture repository into a golden dataset. Define a versioning policy for the CLI JSON contract. | The same canonical snapshot, change, and plan status can be regenerated from the same fixture. |
| Stage 1 | Canonical artifact/version/relation/evidence schema. Markharness native importer and JUnit evidence importer. Distinguish stored/derived trace origin. import --format json. |
Version-aware plan status can be reproduced in CI from native knowledge and JUnit results. |
| Stage 2 | Base/head diff collection. Affected-existing-tests via stored/derived trace. Rule-based missing-test inspection. Optional AI proposal adapter. markharness plan --base --head --format json. |
Evaluation results (precision/recall, etc.) comparing the plan against human-selected plans are obtained on a historical PR dataset. |
| Stage 3 | Read-only Release Verification Dashboard and Feature History via markharness serve. |
The target users can explain a release’s remaining verification work faster than with CLI/files alone. |
Stage 4 (external import expansion, PR check/comment integration) and Stage 5 (collaborative SaaS) are conditional, premised on the completion of Stage 0–3 and observed usage; this ADR does not fix their order of work (Section 4).
The following are recorded as boundaries the product will not put at the forefront. If, during implementation, a proposal arises that would cross one of these boundaries, its merit is judged in a new ADR.
Work on Stage 5 (collaborative SaaS: RBAC, SSO, a shared DB, etc.) is considered only once the following conditions are confirmed. It is not started as of this ADR.
Stage 4 (an importer from an existing TMS such as TestRail, GitHub/GitLab PR check integration) is started after the Stage 2 Verification Plan PoC shows practically useful accuracy (precision/recall). The TestRail importer is deferred until demand is confirmed, and the Stage 1 importer rollout order is “Markharness native → JUnit XML → Gherkin → Playwright → Doorstop/StrictDoc → TestRail” (file-based sources first, with SaaS-API-specific authentication, pagination, and rate-limit handling deferred to later stages; Section 3.8 of the integrated design document).
Based on the proposals in Section 9 of the integrated design document, the following maintain/reduce policy is adopted.
Maintain and strengthen: structured test knowledge, deterministic TestCase generation, Feature version via Git tree SHA, milestone/snapshot diff, change-to-affected-TestCase derivation, version-binding of execution evidence, derived pending/re-verification, the file/CLI workflow. All of these are core to the current implementation (Chapter 3 of the paper) and remain unchanged.
Reduce and redesign: Generalize the milestone-only UX into a common version range that adds PR base/head as first-class (undertaken in Stage 2). Do not rely solely on human-oriented text output; give stable JSON/schema equal or greater weight (undertaken in Stage 0–1). Consolidate the simple PASS/FAIL display so that it uses, as tracking input, the valid/stale/unknown classification already provided by verify trace/verify pending (Section 3.7 of the paper).
Stages 0–3 are implemented as one product in one repository, using a modular monolith with Git as the source of truth. A web server, shared database, resident worker, and microservices are not prerequisites of the Domain Engine. The existing Rust CLI is not rewritten wholesale. Its deterministic generation, Git tree SHA comparison, real-Git fixture tests, fs_safety, and reuse of changes compute by backfill are retained.
| Module | Responsibility | Main Interface |
|---|---|---|
KnowledgeWorkspace |
Load and normalize knowledge/ and axes/, validate references and schemas, and build a Knowledge Snapshot |
load, validate, snapshot, apply |
TestcaseCompiler |
Deterministically generate TestCases and the traceability index from a Snapshot | compile(snapshot) -> GeneratedArtifacts |
ChangeAnalyzer |
Compare Feature tree SHAs over arbitrary from/to CommitRefs and derive ChangeEvents, impacted TestCases, and true_divergences |
compute(from, to, options) -> ChangeSet |
VerificationEngine |
Derive valid/pending/stale/unknown from ChangeEvents and version-bound execution evidence | trace(input), pending(input) |
BackfillCoordinator |
Select unprocessed version ranges, invoke ChangeAnalyzer, and record progress in Git notes |
run_once(policy) -> BackfillSummary |
The CLI, CI summary, and Stage 3 GUI do not reimplement Domain Engine calculations. They express the same result types returned by Application Use Cases through different Presentations. The dependency direction is Presentation -> Application -> Domain -> Infrastructure. decision 0009 is authoritative for Module Interfaces, CommitRef, KnowledgeSource, atomic generated-artifact replacement, and incremental migration; domain-application-infrastructure-layering-design.md is authoritative for the detailed design.
The first kind of scale improved in Stages 0–3 is not server count, but the number of features, volume of code, number of tests, and number of developers. Stable Interfaces between Domain Modules and Application Use Cases increase locality of change and reuse across CLI, CI, and GUI.
Performance for increasing Knowledge, milestone, and execution counts is improved in the following correctness-preserving order.
GitTreeKnowledgeSource to read historical commits directly from Git trees/blobs.backfill run.Full generation and verification remain the canonical operations. Incremental processing and indexes are deletable, reconstructible optimizations. Horizontal scaling, a shared database, and a distributed job queue are not introduced until the Stage 5 entry conditions are met. The detailed Phases 1–5 and test strategy are delegated to decision 0009 and its design document.
The Stage 3 GUI does not begin as a separate product or repository. It is implemented as an independent frontend package in the same repository as markharness. The product remains one, while the Domain Engine, Application, CLI, localhost server, and frontend are separate Modules/packages in code.
markharness/
crates/
markharness-domain/
markharness-application/
markharness-git/
markharness-cli/
markharness-server/
ui/
schema/
tests/fixtures/
tests/golden/
This is a target responsibility layout, not a requirement to split crates immediately in Stage 0. Interfaces and dependency direction are established inside the existing crate first. A Module moves into a workspace crate when independent build, dependency management, or release value exists.
markharness serve --dir <repository> is a localhost-only read-only server that supplies versioned read models generated by the Domain Engine and serves static GUI assets. The GUI does not independently calculate ChangeEvents, evidence freshness, or Verification Plan status. It displays the Domain Engine’s valid/pending/stale/unknown values and their reason/source/confidence.
The public contract is markharness plan --format json and its versioned JSON Schema. The Stage 3 localhost HTTP Interface begins as an internal Interface within the same release and initially makes no long-term compatibility promise to external clients. Release builds bundle the frontend’s static artifacts with the Rust binary, so users do not need a Node.js environment.
Moving the GUI to a separate repository is reconsidered in a new ADR if any of the following becomes true.
ChangeEvent, verified_feature_tree_shas, etc.).