truthmark/docs/truthmark/engineering/repository/repository-intelligence.md

status, truth_kind, last_reviewed

status	truth_kind	last_reviewed
active	engineering-behavior	2026-06-26

Repository Intelligence

Purpose

This doc owns checkout-derived repository-intelligence artifacts used by agents and CLI output.

Scope

It covers RepoIndex, RouteMap, ImpactSet, evidence validation, freshness, and WorkflowState/action-context behavior.

Current Implementation Behavior

• RepoIndex and RouteMap are derived from the active checkout.

• They preserve repository metadata, discovered files, truth docs, test files, route lane metadata, and route-local relationship metadata.

• RouteMap emits duplicate truth document entries with the same path, kind, and lane as one relationship view whose realized_by, realizes, and depends_on metadata is merged by unique sorted set.

• RepoIndex derives truth-doc lane and doc type from truth_kind when canonical truth docs omit explicit truth_lane and doc_type frontmatter.

• Repository intelligence is language-neutral workflow context, not a language-semantic code index.

• Truthmark does not maintain import graphs, export lists, public-symbol tables, or language-specific symbol validation.

• Agents inspect source code directly.

• These artifacts guide routing, context selection, verification planning, and write boundaries without overriding source files, route files, truth docs, or workflow write boundaries.

• ImpactSet remains the branch-diff routing handoff for changed files, affected routes, affected truth docs, affected tests, and diagnostics.

• It derives affected routes from route code surfaces and truth-doc ownership, derives affected tests from changed test paths and path/name hints, and reports diagnostics for unmapped functional-code changes.

• It does not report TypeScript public-symbol changes or use TypeScript/JavaScript import parsing to infer affected tests.

• WorkflowState is the workflow-scoped advisory handoff for:

  • helper readiness
  • a workflow card
  • write-boundary suggestions
  • target truth docs
  • optional helper commands
  • review checklist
  • compact affected-test guidance
  • diagnostics
  • next steps
  • report sections

• The advisory card presents affected files, likely route owners, suggested truth docs, open questions, and skipped optional-helper status so helper output remains review material rather than repository authority.

• Workflow applicability uses context-shaped states such as ready, needs_manual_review, and needs_routing_review.

• Diagnostics or missing route ownership produce open questions and manual handoff guidance instead of making the CLI the arbiter.

• truthmark-sync includes Sync Intent in its report sections as a transient pre-write checklist and keeps affected truth docs in targetTruthDocs for review focus.

• Sync action context separates primaryTruthDocs, candidateStaleTruthDocs, and routeFiles.

• Agents start with impacted route owners.

• Stale candidates are included only when a concrete signal exists.

• Stale-candidate signals include freshness diagnostics naming a truth doc.

• Stale-candidate signals include route relationships through realized_by, realizes, or depends_on.

• Stale-candidate signals include truth docs whose source_of_truth references changed files.

• Stale-candidate signals include changed route metadata and changed linked counterpart docs.

• When no signal exists, candidateStaleTruthDocs is empty; agents may still inspect another document when direct checkout evidence reveals a stale claim.

• The standalone ContextPack handoff is retired.

• Agents use workflow status plus impact as optional guidance and continue with direct checkout inspection when helpers are skipped or unavailable.

• These outputs do not emit source-file or truth-doc body contents.

• Evidence validation checks repository containment, referenced file or glob existence, line spans, and sha256: content hashes.

• Evidence symbol metadata, when present in an evidence YAML block, is non-normative metadata and is not validated through TypeScript-specific parsing.

• Generated-surface diagnostics are checkout-derived repository intelligence for the installed workflow runtime.

• truthmark check compares rendered generated surfaces with committed files and reports missing or stale generated host-native skill package files so skill-directory resources stay colocated with SKILL.md.

Core Rules

• Repository intelligence is advisory checkout context, not hidden memory or off-repo authority.
• WorkflowState and ImpactSet expose paths, metadata, diagnostics, and checklists without embedding source-file or truth-doc bodies.
• Route relationships remain route-local metadata.

Behavior Scenarios

Scenario: Impact maps branch changes to review focus

• GIVEN a branch changes source, test, route, or truth-document paths
• WHEN Truthmark builds an ImpactSet for the branch
• THEN it reports affected routes, affected truth docs, affected tests, and unmapped functional-code diagnostics
• AND it does not infer TypeScript public-symbol changes through language import parsing

Scenario: Workflow status keeps stale candidates signal-based

• GIVEN a changed file maps to primary truth docs and no concrete stale-truth signal names another doc
• WHEN Sync action context is built
• THEN candidateStaleTruthDocs remains empty
• AND agents may still inspect another document only when direct checkout evidence reveals a stale claim

Scenario: Evidence validation stays repository-contained

• GIVEN truth evidence names a repository path, glob, line span, or sha256: hash
• WHEN Truthmark validates evidence
• THEN it checks repository containment and referenced file or glob existence
• AND it treats optional symbol metadata as non-normative metadata rather than TypeScript-specific proof

Flows And States

• RepoIndex and RouteMap are built from committed repository files.
• ImpactSet maps branch changes to affected routes, truth docs, and tests.
• WorkflowState packages workflow-specific handoff data and open questions.
• Evidence validation checks referenced paths, globs, line spans, and hashes.

Contracts

• Public JSON shapes are contract truth owned by docs/truthmark/engineering/contracts/config-route-and-check-contracts.md.
• Generated-surface freshness behavior is contract truth owned by docs/truthmark/engineering/contracts/generated-host-surfaces.md.

Product Truth Links

• docs/truthmark/product/capabilities/lane-separated-truth.md

Engineering Decisions

• Decision (2026-06-14): Repository intelligence is derived context, not hidden memory or off-repo authority.
• Decision (2026-06-15): Repository intelligence is a language-neutral workflow helper, not a semantic code index; TypeScript-specific import/export/public-symbol analysis is not part of the public contract.
• Decision (2026-06-15): The standalone ContextPack handoff is retired.
  • Agents use truthmark workflow status --workflow <workflow> [--base <ref>] --json for optional workflow-scoped guidance and truthmark impact --base <ref> --json for branch-diff routing.
• Decision (2026-06-16): workflow status is status/debug/handoff only.
  • Truthmark does not expose a workflow instructions command and generated workflows must remain usable from committed repository files without live CLI preflight.
• Decision (2026-06-17): WorkflowState presents optional helper output as an advisory workflow card.
  • The advisory card includes affected files, likely route owners, suggested truth docs, open questions, skipped helper status, reviewChecklist, and evidencePrompts.
  • It does not expose retired enforcement-shaped names such as checks.required, the old gate alias, or requiredEvidence.
• Decision (2026-06-16): Sync Intent is a transient report-section checklist exposed through workflow/report surfaces and WorkflowState report sections; it is not repository-intelligence state or a persisted plan.
• Decision (2026-06-17): Generated-surface freshness includes host-native package diagnostics.
  • These diagnostics are review output and do not add hooks, live services, duplicate workflow packages, or mandatory workflow preflight execution.
• Decision (2026-06-21): Sync candidateStaleTruthDocs stays signal-based.
  • WorkflowState does not enumerate every indexed truth doc outside the impact set.
  • It returns an empty candidate list unless freshness, relationships, source references, changed route metadata, or changed linked docs indicate a possible stale-truth repair.

Rationale

Compact repository intelligence saves agent context by pointing to likely routes and evidence without replacing direct checkout inspection.

Non-Goals

• Repository intelligence does not maintain language-specific semantic indexes.
• Repository intelligence does not emit complete file contents.
• WorkflowState does not execute workflows or decide final correctness.

Maintenance Notes

Update when index, route-map, impact, evidence, freshness, or workflow-state output changes.

Source References

• src/repo-index/build.ts
• src/repo-index/file-tree.ts
• src/repo-index/route-map.ts
• src/repo-index/types.ts
• src/impact/build.ts
• src/impact/types.ts
• src/evidence/validate.ts
• src/workflow-state/action-context.ts
• src/workflow-state/build.ts
• src/workflow-state/types.ts
• src/checks/generated-surfaces.ts
• tests/impact/build.test.ts
• tests/evidence/validate.test.ts
• tests/workflow-state/build.test.ts