a083b703fa
* feat: add OpenSpec-driven workflow state * docs: plan generated playbooks workflow contract * feat: add truth health scorecard Release Truthmark 2.1.0 with check JSON scorecard output. Archive the completed OpenSpec pass 4 scorecard change and update generated truth surfaces. * fix: unblock truthmark scorecard review - restore and update coverage for scorecard/evidence/workflow behavior - make truthmark-sync select a cheap local base when --base is omitted - report malformed evidence YAML blocks as diagnostics instead of throwing * fix: tighten workflow boundaries * fix: fail closed when sync has no comparison base * fix: tighten truth health review coverage - only parse fenced YAML evidence blocks with top-level evidence markers - convert coverage fixtures to valid v2 config and assert non-vacuous diagnostics - update Truthmark truth docs for source traceability and workflow-state tests * docs: clarify source traceability diagnostics * docs: harden optional CLI workflow boundary * docs: clarify product boundary is repo-local * fix: bound truthmark workflow fallback behavior - make live workflow preflight use the one-call instructions contract - keep missing-CLI fallback bounded for Sync, Document, Structure, and Realize - add routing and generated-surface coverage plus refreshed host surfaces * test: cover no-cli workflow fallback bounds - assert route-first fallback wording in generated workflow surfaces - clarify progressive-disclosure support files are conditional - align overview docs with bounded no-CLI behavior * docs: route workflow eval coverage * fix: remove workflow instructions preflight * fix: remove stale workflow preflight wording * fix: remove generic workflow validation blocks * fix: avoid duplicated markdown context JSON * fix: keep workflow status manifest-only * docs: align truth docs with v2 hierarchy --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
3.2 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/truthmark/truth/init-and-scaffold.md
- Change to diagnostics, routing, containment, or branch scope: update docs/truthmark/truth/check-diagnostics.md
- Change to installed workflow text, skip reasons, report shape, or ownership gates: update docs/truthmark/truth/workflows/overview.md and the relevant bounded doc under
docs/truthmark/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 .agents/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/routes/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/routes/areas.md as the root route index and docs/truthmark/routes/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.