mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
MerlinHandGitHub
caced773f5
* refactor(truthmark): parameterize truth agent paths with routing config * 1.2.4 truth flow research * Context and workflow optimization
4.8 KiB
4.8 KiB
status, doc_type, last_reviewed, source_of_truth
| status | doc_type | last_reviewed | source_of_truth | |
|---|---|---|---|---|
| active | architecture | 2026-05-14 |
|
Module Map
Purpose
This is the quick module-level map for the current Truthmark codebase.
Scope
This doc covers the current module grouping of the Truthmark codebase and the primary canonical docs that pair with those modules.
Components
- CLI and config loading:
src/cli/,src/config/, and shared result rendering. - Scaffold and generated surfaces:
src/init/,src/templates/, and containment-safe write helpers insrc/fs/. - Routing and checks:
src/routing/,src/checks/,src/markdown/, and repository discovery insrc/git/. - Installed workflow support:
src/agents/,src/generation/,src/sync/,src/realize/, and neutral truth helpers insrc/truth/.
Source Layout
| Path | Responsibility |
|---|---|
src/cli/ |
Commander program setup and command dispatch |
src/init/ |
Config-aware repository scaffold orchestration plus hierarchy migration checks |
src/templates/ |
Text templates for scaffolded files, the AGENTS block, generated-surface manifests, and generated host-specific explicit surfaces |
src/checks/ |
Validation passes for authority, areas, generated surfaces, decision-bearing docs, frontmatter, links, and branch scope |
src/config/ |
.truthmark/config.yml schema and loader |
src/routing/ |
Parsing of the root route index and delegated child route files |
src/markdown/ |
Markdown discovery, parsing, and hashing helpers |
src/fs/ |
Repository-safe path resolution and file writes shared by init and diagnostics |
src/generation/ |
Source-internal content prompt contracts, JSON-safe prompt rendering, and structured draft validation |
src/truth/ |
Neutral helpers for truth root resolution and evidence report formatting shared by scaffold, checks, sync, and agent renderers |
src/git/ |
Git repository and worktree resolution plus change listing |
src/sync/ |
Truth Sync policy and completed, skipped, or blocked report rendering |
src/agents/ |
Installed Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check instruction text plus shared worker and skill contract fragments |
src/realize/ |
Truth Realize report rendering |
src/output/ |
Diagnostic types plus human and JSON rendering shared by CLI and check flows |
src/types/ |
Local type shims |
tests/ |
Vitest coverage for CLI, checks, routing, templates, and helpers |
Practical Routing
- If the change affects scaffolded file contents or generated skill surfaces, start in
src/templates/andsrc/init/. - If the change affects diagnostics, start in
src/checks/andsrc/output/. - If the change affects installed workflow text, content prompt contracts, or explicit skill surfaces, start in
src/agents/,src/generation/,src/sync/,src/realize/, andsrc/templates/. - If the change affects path safety or repository detection, start in
src/fs/andsrc/git/.
Documentation Pairings
src/init/,src/templates/, and the write-path parts ofsrc/fs/pair with docs/truth/init-and-scaffold.mdsrc/checks/,src/routing/,src/config/,src/output/, and the containment-path parts ofsrc/fs/pair with docs/truth/check-diagnostics.mdsrc/agents/,src/generation/,src/sync/,src/realize/,src/truth/, and installed workflow skill templates undersrc/templates/pair with docs/truth/workflows/overview.md and bounded workflow docs underdocs/truth/workflows/
Product Decisions
- Route ownership stays in Markdown route files rather than being duplicated into config objects.
src/agents/andsrc/templates/render configured hierarchy and decision-truth guidance directly into installed workflow surfaces.- Content-generation prompt contracts live outside
src/agents/so workflow authority and draft-content shaping remain separate. src/checks/decisions.tsbelongs with the validation layer because decision-bearing canonical docs are a truth-health concern, not an authoring convenience.- Shared truth-root and evidence formatting helpers live in
src/truth/so scaffold, checks, sync reports, and generated agent text do not duplicate the same domain defaults.
Rationale
This split keeps layout contract, route ownership, validation, and generated workflow text in predictable places. Agents and maintainers can change one surface without rediscovering unrelated behavior hidden elsewhere.
The generation layer is source-internal in this slice because current packaging builds only the CLI entrypoint. Keeping prompt contracts separate from installed workflow renderers preserves the existing workflow authority model while giving future workflow code a tested draft-contract layer to consume.