truthmark/FutureVision.md

Directions for V2

Priority order: Evidence and Adoption first. Conformance continuously. Propagation and
Decision Architecture in a later pass when the core confidence surface is stable.

---

V2.0 — Ship First

1. Evidence Layer
   - Strengthen `truthmark check` into the primary confidence surface. Error diagnostics
     should be the canonical signal of truth health, not a secondary linting step.
   - Make check output more actionable: route precision score, unmapped code surfaces, stale
     generated surfaces, topology pressure hotspots in one readable report.
   - Expose stable JSON output from `truthmark check` so CI, PR bots, and future adapters
     can consume truth health without parsing human-readable text.
   - Add lightweight traceability reporting: which routed docs have explicit code ownership,
     active decisions, and at least one verification link. This is coverage for Truthmark's
     narrower scope, not full MBSE traceability.
   - Build before/after demos: code change -> tests -> Truth Sync -> reviewable truth diff.

2. Adoption Layer
   - Create high-quality example repos: Node API, Go service, frontend app, monorepo, infra
     repo. Each one should show a real Truth Sync cycle, not just the installed scaffolding.
   - Add migration guides for teams already using AGENTS.md, CLAUDE.md, Copilot
     instructions, or Gemini commands. The entry point is their existing agent config, not
     a blank repo.
   - Sharpen messaging: "Your agents write code. Truthmark makes their context reviewable in
     Git."
   - Reduce vocabulary friction. "Truth" is powerful internally, but new users need concrete
     outcomes: fewer repeated decisions, better handoffs, less doc drift.
   - Show comparative stories: prompt-only repo vs Truthmark repo, broad route vs precise
     route, undocumented change vs reviewable truth diff. These replace the abstract truth
     explorer idea; showing is better than a browseable demo that requires building a separate
     site product.

---

V2.x — Steady Conformance (ongoing alongside V2.0)

3. Conformance Layer
   - Treat generated host surfaces as adapters with contract tests covering each platform
     (Codex, Claude Code, Copilot, OpenCode, Gemini CLI). Host API evolution is the main
     breakage risk; tests catch it before users do.
   - Keep all configured platforms current as those hosts evolve. External signal: Codex
     reads repo instructions and skills; Copilot supports repo/path/agent instructions;
     Claude Code has project skills; Gemini CLI supports project commands.
   - Keep MCP and IDE integrations as optional adapter surfaces only. They must not become
     the product center of gravity. Truthmark is a repository protocol, not a server.

---

V2.5 — Next Wave

4. Propagation Layer
   - Inspired by Reqvire's change-propagation concept, but scoped to Truthmark's narrower
     model: route-aware, not requirement-graph-aware.
   - For code-first changes, Truth Sync should emit "likely stale" hints when a change
     touches code owned by multiple routes or when owned docs have not been touched in the
     same branch. This is a check signal, not an automatic rewrite.
   - For doc-first changes, Truth Realize should emit a bounded implementation checklist
     (which code files are owned by the changed doc, what tests cover them) before the agent
     begins writing code. Reduces scope drift.
   - Treat active decisions as reviewable objects: a truth diff that shows a Product Decision
     change should surface which code areas and tests that decision governs. Reviewers should
     not need to reconstruct the impact manually.

5. Decision Architecture (New Idea — Evaluate Before Building)
   - Proposal: separate business decisions from technical decisions by where they live.
     Business decisions (what the PM decided the product must do and why) belong in truth
     docs. Technical decisions (why this implementation approach, which trade-offs were made
     in code) can live as structured comments in the code.
   - The existing Product Decisions / Rationale section structure in canonical docs already
     approximates this: "Product Decisions" is the business layer, "Rationale" is the
     technical justification.
   - Opportunity: make this convention explicit, validated, and agent-readable. `truthmark
     check` could warn when a Product Decisions section reads like an implementation note
     (contains file names, library names, performance numbers) rather than product intent.
   - Risk 1: the boundary is blurry. "We chose PostgreSQL because the team knows it" is a
     technical decision with an organizational cause; "we chose eventual consistency because
     the PM wants fast writes" is a business decision that shapes technical choices. Many
     real decisions span both.
   - Risk 2: code comments don't survive refactoring. They drift more than truth docs, which
     have routing, check, and Truth Sync discipline.
   - Risk 3: agents crossing two locations (truth doc for the what, code for the why) is
     more expensive than one location with both. The protocol should be clear about which
     agent reads what.
   - Better formulation: truth docs own product intent and the business rationale for
     decisions. Technical trade-offs and implementation rationale should also appear in truth
     docs when the trade-off is decision-bearing (likely to be revisited or affects contract
     boundaries). Implementation-local detail (why this loop is structured this way) belongs
     in code comments and is outside Truthmark's scope.
   - Verdict: validate the convention with example repos before encoding it as a validated
     check. It is a governance principle, not a structural enforcement.

---

Non-Goals (What Truthmark Should Not Become)

These are competitive directions that feel adjacent but would dilute the product:

- A full requirements or MBSE platform (that is Reqvire's lane).
- A memory server or session-persistence tool.
- A spec or PRD authoring tool.
- An IDE or editor plugin (adapter surfaces only, not first-party tooling).
- A merge gate or CI approval system (truth health is a signal, not an enforcement layer by
  default).

---

Market Position

Reqvire validates demand for Git-native, Markdown-based, AI-readable context with
traceability and coverage. ADRs (15k GitHub stars) validate demand for decision-record
discipline across teams. Decision Guardian validates demand for decision-to-code surfacing at
PR review time.

The gap Truthmark owns is narrower and more opinionated: branch-scoped repository truth
as a governance layer, not a requirements system and not a memory tool. The value is that
agent context becomes a committed, reviewable, branch-local Git artifact instead of a
session-private opaque record.

If Reqvire is requirements-as-context and ADRs are decision-as-document, Truthmark is
repository-truth-as-governance: what is authoritative on this branch, what code it owns,
what changed, and what must be updated before work is complete.

> The repo should tell every AI agent what is true, what owns what, what changed, and what
> must be updated before work is complete.