feat: add Truthmark health scorecard and bounded workflow contracts (#13)

* 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>

docs/standards/default-principles.md

@@ -94,7 +94,7 @@ Truthmark can provide places for those rules to live, but the content should bel
 When a repository has no explicit standards yet, a small default baseline is reasonable:
 
 - a documentation governance standard
-- authority and routing entrypoints such as `.truthmark/config.yml` and `docs/truthmark/areas.md`
+- authority and routing entrypoints such as `.truthmark/config.yml` and `docs/truthmark/routes/areas.md`
 - a verification standard with canonical commands and skip rules
 - a completion checklist or equivalent completion gate
 

docs/standards/documentation-governance.md

@@ -45,8 +45,8 @@ Truthmark's minimal canonical surface is:
 
 - `docs/ai/repo-rules.md` as the repository-wide agent policy source
 - `.truthmark/config.yml` as the committed hierarchy contract
-- `docs/truthmark/areas.md` as the primary routing surface
-- the project's canonical truth docs under directories such as `docs/standards/`, `docs/architecture/`, and `docs/truth/`
+- `docs/truthmark/routes/areas.md` as the primary routing surface
+- the project's canonical truth docs under directories such as `docs/standards/`, `docs/architecture/`, and `docs/truthmark/truth/`
 
 By default, instruction files such as `AGENTS.md` install workflow behavior. They do not outrank the canonical truth surface unless a project opts into that explicitly.
 
@@ -83,7 +83,7 @@ Do not create separate timestamped ADR folders, planning tickets, or historical
 - Behavior changes and truth-doc updates should land in the same working change when possible.
 - Major product, onboarding, install, command, positioning, or workflow changes should include a root README review in the same working change. Update the README when its human-facing claims, examples, or command sequences are stale.
 - When the root README has localized variants, keep them aligned with the English README for materially changed install, command, positioning, and workflow guidance in the same working change, or explicitly document why a variant intentionally differs.
-- When routing changes, update `docs/truthmark/areas.md` and any affected canonical docs together.
+- When routing changes, update `docs/truthmark/routes/areas.md` and any affected canonical docs together.
 - When routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, run Truth Structure before adding more generic truth docs.
 - When a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership, update the owning architecture doc in the same change.
 - Do not update architecture docs for ordinary product behavior unless that behavior changes an architecture boundary.
@@ -111,7 +111,7 @@ Do not create separate timestamped ADR folders, planning tickets, or historical
 - Does this document have one primary responsibility?
 - Does each class of fact have one canonical source?
 - Is this fact stored in the correct document class?
-- Does `docs/truthmark/areas.md` route the changed area to the right truth docs?
+- Does `docs/truthmark/routes/areas.md` route the changed area to the right truth docs?
 - If routing is broad or overloaded, has Truth Structure repaired topology before new truth docs were created?
 - Are duplicated or shadow documentation paths being avoided?
 - Is generated helper output still treated as non-authoritative rather than truth?

docs/standards/maintaining-repository-truth.md

@@ -16,9 +16,9 @@ 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](../truth/init-and-scaffold.md)
-- Change to diagnostics, routing, containment, or branch scope: update [docs/truth/check-diagnostics.md](../truth/check-diagnostics.md)
-- Change to installed workflow text, skip reasons, report shape, or ownership gates: update [docs/truth/workflows/overview.md](../truth/workflows/overview.md) and the relevant bounded doc under `docs/truth/workflows/`
+- Change to scaffolded files or AGENTS management: update [docs/truthmark/truth/init-and-scaffold.md](../truthmark/truth/init-and-scaffold.md)
+- Change to diagnostics, routing, containment, or branch scope: update [docs/truthmark/truth/check-diagnostics.md](../truthmark/truth/check-diagnostics.md)
+- Change to installed workflow text, skip reasons, report shape, or ownership gates: update [docs/truthmark/truth/workflows/overview.md](../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](../ai/repo-rules.md) or the relevant standard
 
 ## Maintaining AGENTS.md
@@ -30,9 +30,9 @@ Treat [AGENTS.md](../../AGENTS.md) as two surfaces:
 
 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`.
+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/areas.md
+## Maintaining docs/truthmark/routes/areas.md
 
 When code boundaries or canonical docs change:
 
@@ -40,7 +40,7 @@ When code boundaries or canonical docs change:
 2. narrow overly broad truth-doc lists instead of adding more shadow docs
 3. make sure every relevant `src/**` file still matches at least one area mapping
 
-With hierarchical routing, treat [docs/truthmark/areas.md](../truthmark/areas.md) as the root route index and `docs/truthmark/areas/**/*.md` as the delegated child route files. Keep delegation to one level.
+With hierarchical routing, treat [docs/truthmark/routes/areas.md](../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
 

docs/standards/pre-completion-checklist.md

@@ -21,7 +21,7 @@ Use this checklist before declaring Truthmark work complete.
 - If behavior, contracts, or workflow text changed, did the nearest canonical docs change in the same working change?
 - If this was a major product, onboarding, install, command, positioning, or workflow change, did you review the root [README.md](../../README.md) and update stale user-facing claims, examples, or command sequences?
 - If the root README changed materially, did the localized README variants change in the same working change? If not, stop unless you have an explicit repo-authorized reason they intentionally remain different, and state that reason. A passing verification command does not waive this gate.
-- If canonical routing changed, did [docs/truthmark/areas.md](../truthmark/areas.md) change too?
+- If canonical routing changed, did [docs/truthmark/routes/areas.md](../truthmark/routes/areas.md) change too?
 - If the change is PR-worthy, release-worthy, or changes the package version, did you add or update a `changes/` note using [docs/standards/change-notes.md](change-notes.md)?
 - If any package version or release/version policy changed, did you apply [docs/standards/versioning.md](versioning.md) before accepting the version?
 - If [AGENTS.md](../../AGENTS.md) changed, did manual edits stay outside the managed Truthmark block?

docs/standards/template-standards.md

@@ -98,4 +98,4 @@ Truthmark defaults are justified because they optimize for the reviewable artifa
 
 Update this standard when Truthmark adds, removes, renames, or materially changes default truth-document templates, or when the references behind the default template rationale change.
 
-When changing default template content, keep `docs/templates/*.md`, `src/templates/init-files.ts`, `docs/standards/default-principles.md`, and this standard aligned.
+When changing default template content, keep `docs/truthmark/templates/*.md`, `src/templates/init-files.ts`, `docs/standards/default-principles.md`, and this standard aligned.