MerlinHandGitHub
caced773f5
* refactor(truthmark): parameterize truth agent paths with routing config * 1.2.4 truth flow research * Context and workflow optimization
3.1 KiB
status, doc_type, last_reviewed, source_of_truth
| status | doc_type | last_reviewed | source_of_truth | |||
|---|---|---|---|---|---|---|
| active | guide | 2026-05-09 |
|
Maintaining Repository Truth
Purpose
This guide is for humans maintaining Truthmark's own docs tree.
When To Update Which Docs
- Change to scaffolded files or AGENTS management: update docs/truth/init-and-scaffold.md
- Change to diagnostics, routing, containment, or branch scope: update docs/truth/check-diagnostics.md
- Change to installed workflow text, skip reasons, report shape, or ownership gates: update docs/truth/workflows/overview.md and the relevant bounded doc under
docs/truth/workflows/ - Change to repository-wide rules or completion policy: update docs/ai/repo-rules.md or the relevant standard
Maintaining AGENTS.md
Treat AGENTS.md as two surfaces:
- manual repository-specific guidance outside the managed block
- the generated Truthmark block between
<!-- truthmark:start -->and<!-- truthmark:end -->
Do not hand-edit the managed block for one-off wording changes. Change the template source instead, then refresh the block through the normal workflow.
Generated Truthmark skill files under .codex/skills/ and .opencode/skills/ follow the same rule. Edit the renderers in src/agents/ and src/templates/, then refresh through truthmark init.
Maintaining docs/truthmark/areas.md
When code boundaries or canonical docs change:
- update the routed truth docs for the affected area
- narrow overly broad truth-doc lists instead of adding more shadow docs
- make sure every relevant
src/**file still matches at least one area mapping
With hierarchical routing, treat docs/truthmark/areas.md as the root route index and docs/truthmark/areas/**/*.md as the delegated child route files. Keep delegation to one level.
Changing Hierarchy
When hierarchy changes:
- edit
.truthmark/config.yml - run
truthmark init - review migration diagnostics
- move docs and route files manually
- run
truthmark check - commit config, routing, and docs together
truthmark init creates missing structure but does not move or delete existing truth docs for you.
Changing Decisions
When a product or architecture decision changes, edit the Product Decisions and Rationale sections in the owning canonical doc in the same change as code and routing updates.
Date active decisions inline when added or changed, for example Decision (2026-05-09): ....
Do not preserve the old active decision in a parallel file. Git history preserves it.
Historical Material
If a historical note becomes current truth, rewrite it into the correct canonical class under docs/ instead of linking to old planning material as if it were the maintained source.
Verification
Run docs/standards/testing-and-verification.md commands appropriate to the change. For docs-only routing work, npm run dev -- check is the default validation step.