17ed1599a3
* fix: harden workflow helper manifests and reports * docs: add helper script portability design * fix: reject failed helper statuses in completed reports * fix: align helper report sections metadata * fix: preserve sync helper statuses in parser * test: harden helper validator negatives * feat: add Copilot and Gemini Truthmark surfaces - generate Copilot and Gemini workflow skill packages with helper manifests - add Gemini subagent surfaces and validate helper CLI plumbing - update README/docs for helper-package support Verification: npm run check * docs: simplify README workflow surface overview Replace long generated file lists with conceptual layers and Mermaid architecture diagrams across localized READMEs. Verification: node dist/main.js check --json; npm run package:check * docs: show agent CLI feedback loop in README diagram Clarify that host-native agent workflows can call the installed Truthmark CLI for validation, indexing, and helper checks. Verification: node dist/main.js check --json; npm run package:check * fix: wrap validate JSON output in command envelope Return helper validation results under data.validation for --json output while preserving the existing human-readable validate output. Verification: npm run check; truthmark check/index JSON diagnostics. * fix: clarify helper validation status reporting Add explicit helper-status policy to Truth Sync and Truth Document surfaces so standalone Copilot prompts and Gemini commands only report ran/passed after the installed CLI validator succeeds. Update README and workflow docs to describe the shared installed-CLI validator contract instead of saying standalone surfaces mark helper packages unavailable. Verification: npm run check; npm run package:check; truthmark check/index JSON diagnostics. * fix: normalize helper status ids during validation Parse helper status entries with the same regex used for syntax validation and compare captured helper IDs against required helpers. Adds regressions for extra whitespace after helper bullets in Truth Sync and Truth Document reports. Verification: npm run check; npm run package:check; truthmark check/index JSON diagnostics. * fix: parse write lease YAML structurally * chore: bump version to 1.5.0 * docs: include validate in repo CLI boundary * fix: enforce workflow report validator contracts * fix: require manual review files in blocked sync reports --------- Co-authored-by: Hermes Agent <hermes-agent@users.noreply.github.com>
status, doc_type, last_reviewed, source_of_truth
| status | doc_type | last_reviewed | source_of_truth | ||
|---|---|---|---|---|---|
| active | index | 2026-05-15 |
|
Truthmark Docs Index
Purpose
docs/ is Truthmark's canonical repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, and current truth docs separate from onboarding copy and historical planning notes.
AGENTS.md is the agent entry point, but it delegates repository-wide rules to docs/ai/repo-rules.md. README.md remains the human onboarding and product entry point. .truthmark/config.yml defines the committed hierarchy contract.
Scope
This doc defines the current structure, navigation map, and maintenance expectations of Truthmark's canonical docs/ tree.
Authority Source
Repository-wide conflict order and completion policy live in docs/ai/repo-rules.md. Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
README.md may help with onboarding and positioning, but it must not override current-state docs or repository-wide agent rules.
Audience Split
Agent-centric docs
docs/ai/for repository rules and agent onboardingdocs/truthmark/for routing metadatadocs/standards/for reusable constraints and completion rulesdocs/architecture/for current system structuredocs/truth/for current behavior and invariantsdocs/templates/for editable scaffold templates used to create new docsdocs/truth/contracts.mdfor stable contracts the CLI exposes
Human-centric docs
- README.md for onboarding and positioning
Directory Map
| Path | Type | Primary audience | Purpose |
|---|---|---|---|
docs/ai/ |
agent rules | agent | Repository-wide rules and fast onboarding |
docs/truthmark/ |
routing | both | Truth-routing metadata such as areas.md and areas/**/*.md |
docs/standards/ |
standard | agent | Reusable constraints, verification rules, completion gates |
docs/architecture/ |
architecture | agent | Current structure and module boundaries |
docs/truth/ |
truth | agent | Current behavior for init, check, contracts, and installed workflows |
docs/templates/ |
template | both | Editable templates for scaffolded docs; templates are not Truth Sync targets |
Frontmatter Policy
Canonical docs should include frontmatter and keep these fields current:
statusdoc_typelast_reviewedsource_of_truth
Update Rules
- When repository-wide agent policy changes, update docs/ai/repo-rules.md.
- When code-to-doc routing changes, update docs/truthmark/areas.md in the same change.
- When package versions or release/version policy change, apply docs/standards/versioning.md before accepting the version.
- When PR or release source text is needed, write a
changes/note using docs/standards/change-notes.md. - When
truthmark initor scaffolded files change, update the relevant truth or architecture doc, not only README.md. - When
truthmark checkchanges what it validates or how it reports diagnostics, update both the current truth doc and the contract doc. - When major product, onboarding, install, command, positioning, or workflow behavior changes, review the root README.md and update it if the human entry point would otherwise be stale.
- Keep planning or proposal material outside the canonical current-state docs until it becomes implemented truth.
- When current behavior changes for architecture, contracts, or truth docs, update the owning canonical doc's
Product DecisionsandRationalesections in the same change. - Do not keep parallel documentation trees for the same subject.
Important Truthmark-Specific Caveat
New repositories should run truthmark config before truthmark init so teams can review the committed hierarchy contract before workflow surfaces are installed. The current scaffold writes a root route index plus one child route file under the configured routing root.
Recommended Reading Order
For humans
- README.md
- .truthmark/config.yml
- docs/ai/repo-rules.md
- docs/architecture/overview.md
- the relevant truth or standard doc for the area being changed
For agents
- docs/ai/repo-rules.md
- docs/ai/agent-onboarding.md, when routing is unclear or cross-area
- docs/truthmark/areas.md, when mapping code to canonical truth
- docs/architecture/module-map.md, when changing module boundaries
- the relevant standard and truth docs for the task
Use docs/truth/routing-examples.md when designing areas for larger API, frontend, infrastructure, or monorepo repositories.
Maintenance Principle
The canonical tree should stay small, explicit, and current. Historical notes are useful for traceability, but current behavior belongs in the nearest maintained document class, not in old plans or chat summaries.
Product Decisions
- Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while docs/ai/repo-rules.md owns repository-wide authority order and completion policy.
Rationale
Keeping the docs index focused on navigation avoids loading duplicated authority prose while still giving agents and maintainers one stable place to resolve where current truth should live before they edit deeper canonical docs.