mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
refactor: simplify Truthmark workflow surfaces (#20)
* refactor: simplify Truthmark workflow surfaces * fix: limit Preview workflow surfaces to supported hosts * docs(truthmark): sync diff-friendly truth docs * fix: prune retired generated surfaces * fix: prune retired generated workflow surfaces * docs: update truthmark architecture and runtime behavior notes * chore: bump version to 2.2.3 --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
This commit is contained in:
Merlin's Cat
@@ -24,5 +24,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- document-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- document report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-document-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -61,6 +61,7 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
@@ -79,12 +80,7 @@ Truthmark hierarchy hints:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
|
||||
- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
|
||||
|
||||
@@ -29,9 +29,6 @@ Evidence checked:
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership.
|
||||
- Truth Preview is read-only; this report is intended, not authorized.
|
||||
- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.
|
||||
- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,10 +0,0 @@
|
||||
interface:
|
||||
display_name: "Truthmark Preview"
|
||||
short_description: "Preview likely workflow routing before edits; read-only and explicit"
|
||||
default_prompt: "Use $truthmark-preview to preview likely Truthmark routing before edits."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,53 +0,0 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
@@ -1,43 +0,0 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/routes/areas.md
|
||||
- likely lane impact: engineering-lane
|
||||
- product target docs: none identified
|
||||
- engineering target docs: docs/truthmark/engineering/behaviors/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truthmark/engineering/behaviors/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Codex subagent mode:
|
||||
- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project agents only: truth_route_auditor
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Preview report
|
||||
@@ -19,20 +19,15 @@ Truth Structure is agent-native:
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/routes/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
|
||||
- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
|
||||
- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
|
||||
- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
- use docs/truthmark/product/** for product truth destinations
|
||||
- use docs/truthmark/engineering/** for engineering truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
|
||||
- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
@@ -52,18 +47,12 @@ Do not:
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
@@ -79,10 +68,10 @@ Use these review thresholds as guidance:
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
|
||||
- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
|
||||
- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
|
||||
- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
|
||||
- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
|
||||
- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
@@ -90,21 +79,12 @@ Repair rules:
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair review:
|
||||
- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Evidence checklist:
|
||||
- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
|
||||
- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
|
||||
- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
|
||||
- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
|
||||
@@ -25,5 +25,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- sync-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- sync report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-sync-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -32,78 +32,33 @@ Parent workflow:
|
||||
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
|
||||
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
|
||||
- Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
|
||||
Topology review:
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
|
||||
Topology review and repair:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
|
||||
- run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that require structure repair
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
|
||||
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that required structure repair
|
||||
- do not create another generic truth doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a README.md index
|
||||
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
|
||||
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Evidence checklist:
|
||||
- route-first: map changed functional files to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
|
||||
- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or record unsupported claims for manual handoff
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
|
||||
- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- stop on any unrelated diff caused by the sync step
|
||||
- stop if functional code changed during sync
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
|
||||
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
|
||||
|
||||
@@ -33,9 +33,6 @@ Evidence checked:
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
|
||||
@@ -24,5 +24,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- document-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- document report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-document-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -61,6 +61,7 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
@@ -79,12 +80,7 @@ Truthmark hierarchy hints:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
|
||||
- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
|
||||
|
||||
@@ -29,9 +29,6 @@ Evidence checked:
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership.
|
||||
- Truth Preview is read-only; this report is intended, not authorized.
|
||||
- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.
|
||||
- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,53 +0,0 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
@@ -1,43 +0,0 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/routes/areas.md
|
||||
- likely lane impact: engineering-lane
|
||||
- product target docs: none identified
|
||||
- engineering target docs: docs/truthmark/engineering/behaviors/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truthmark/engineering/behaviors/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Claude Code subagent mode:
|
||||
- use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents only: truth-route-auditor subagent
|
||||
- subagents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Preview report
|
||||
@@ -19,20 +19,15 @@ Truth Structure is agent-native:
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/routes/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
|
||||
- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
|
||||
- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
|
||||
- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
- use docs/truthmark/product/** for product truth destinations
|
||||
- use docs/truthmark/engineering/** for engineering truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
|
||||
- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
@@ -52,18 +47,12 @@ Do not:
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
@@ -79,10 +68,10 @@ Use these review thresholds as guidance:
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
|
||||
- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
|
||||
- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
|
||||
- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
|
||||
- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
|
||||
- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
@@ -90,21 +79,12 @@ Repair rules:
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair review:
|
||||
- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Evidence checklist:
|
||||
- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
|
||||
- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
|
||||
- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
|
||||
- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
|
||||
@@ -25,5 +25,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- sync-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- sync report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-sync-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -32,78 +32,33 @@ Parent workflow:
|
||||
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
|
||||
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
|
||||
- Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
|
||||
Topology review:
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
|
||||
Topology review and repair:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
|
||||
- run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that require structure repair
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
|
||||
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that required structure repair
|
||||
- do not create another generic truth doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a README.md index
|
||||
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
|
||||
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Evidence checklist:
|
||||
- route-first: map changed functional files to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
|
||||
- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or record unsupported claims for manual handoff
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
|
||||
- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- stop on any unrelated diff caused by the sync step
|
||||
- stop if functional code changed during sync
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
|
||||
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
|
||||
|
||||
@@ -33,9 +33,6 @@ Evidence checked:
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
|
||||
@@ -9,8 +9,6 @@ Read these host-local files in order only as needed:
|
||||
- .gemini/skills/truthmark-document/support/procedure.md
|
||||
- .gemini/skills/truthmark-document/support/report-template.md
|
||||
- .gemini/skills/truthmark-document/support/subagents-and-leases.md
|
||||
- .gemini/skills/truthmark-document/helper-manifest.yml
|
||||
- .gemini/skills/truthmark-document/support/helper-policy.md
|
||||
|
||||
If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
|
||||
User focus or arguments: {{args}}
|
||||
|
||||
@@ -2,14 +2,66 @@ description = "Use when the user explicitly asks to preview likely workflow rout
|
||||
prompt = '''
|
||||
This command is the Gemini CLI entrypoint for Truthmark Preview.
|
||||
|
||||
Do not invoke another Truthmark command from here.
|
||||
Truth Preview is read-only and explicit. Do not invoke another Truthmark command from here.
|
||||
|
||||
Read these host-local files in order only as needed:
|
||||
- .gemini/skills/truthmark-preview/SKILL.md
|
||||
- .gemini/skills/truthmark-preview/support/procedure.md
|
||||
- .gemini/skills/truthmark-preview/support/report-template.md
|
||||
- .gemini/skills/truthmark-preview/support/subagents-and-leases.md
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
|
||||
Invocations: Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Return a concise Truth Preview report with these fields:
|
||||
- requested outcome
|
||||
- likely workflow
|
||||
- why this workflow
|
||||
- likely route owner and lane impact
|
||||
- expected write classes
|
||||
- expected target files
|
||||
- suggested subagent use
|
||||
- manual handoff questions
|
||||
- handoff recommendation
|
||||
User focus or arguments: {{args}}
|
||||
'''
|
||||
|
||||
@@ -9,8 +9,6 @@ Read these host-local files in order only as needed:
|
||||
- .gemini/skills/truthmark-sync/support/procedure.md
|
||||
- .gemini/skills/truthmark-sync/support/report-template.md
|
||||
- .gemini/skills/truthmark-sync/support/subagents-and-leases.md
|
||||
- .gemini/skills/truthmark-sync/helper-manifest.yml
|
||||
- .gemini/skills/truthmark-sync/support/helper-policy.md
|
||||
|
||||
If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
|
||||
User focus or arguments: {{args}}
|
||||
|
||||
@@ -26,5 +26,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- document-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- document report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-document-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -61,6 +61,7 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
@@ -79,12 +80,7 @@ Truthmark hierarchy hints:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
|
||||
- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
|
||||
|
||||
@@ -29,9 +29,6 @@ Evidence checked:
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership.
|
||||
- Truth Preview is read-only; this report is intended, not authorized.
|
||||
- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.
|
||||
- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,53 +0,0 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
@@ -1,43 +0,0 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/routes/areas.md
|
||||
- likely lane impact: engineering-lane
|
||||
- product target docs: none identified
|
||||
- engineering target docs: docs/truthmark/engineering/behaviors/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truthmark/engineering/behaviors/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Gemini CLI subagent mode:
|
||||
- use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out
|
||||
- dispatch read-only project subagents only: @truth-route-auditor
|
||||
- subagents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Preview report
|
||||
@@ -19,20 +19,15 @@ Truth Structure is agent-native:
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/routes/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
|
||||
- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
|
||||
- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
|
||||
- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
- use docs/truthmark/product/** for product truth destinations
|
||||
- use docs/truthmark/engineering/** for engineering truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
|
||||
- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
@@ -52,18 +47,12 @@ Do not:
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
@@ -79,10 +68,10 @@ Use these review thresholds as guidance:
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
|
||||
- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
|
||||
- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
|
||||
- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
|
||||
- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
|
||||
- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
@@ -90,21 +79,12 @@ Repair rules:
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair review:
|
||||
- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Evidence checklist:
|
||||
- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
|
||||
- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
|
||||
- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
|
||||
- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
|
||||
@@ -27,5 +27,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- sync-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- sync report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-sync-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -32,78 +32,33 @@ Parent workflow:
|
||||
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
|
||||
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
|
||||
- Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
|
||||
Topology review:
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
|
||||
Topology review and repair:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
|
||||
- run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that require structure repair
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
|
||||
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that required structure repair
|
||||
- do not create another generic truth doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a README.md index
|
||||
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
|
||||
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Evidence checklist:
|
||||
- route-first: map changed functional files to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
|
||||
- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or record unsupported claims for manual handoff
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
|
||||
- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- stop on any unrelated diff caused by the sync step
|
||||
- stop if functional code changed during sync
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
|
||||
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
|
||||
|
||||
@@ -33,9 +33,6 @@ Evidence checked:
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
|
||||
@@ -17,6 +17,6 @@ Agent runtime: host-native skill packages/adapters plus this block; inspect chec
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
@@ -12,7 +12,5 @@ Read these host-local files in order only as needed:
|
||||
- .github/skills/truthmark-document/support/procedure.md
|
||||
- .github/skills/truthmark-document/support/report-template.md
|
||||
- .github/skills/truthmark-document/support/subagents-and-leases.md
|
||||
- .github/skills/truthmark-document/helper-manifest.yml
|
||||
- .github/skills/truthmark-document/support/helper-policy.md
|
||||
|
||||
If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
|
||||
|
||||
@@ -5,12 +5,64 @@ description: 'Use when the user explicitly asks to preview likely workflow routi
|
||||
|
||||
This prompt is the GitHub Copilot entrypoint for Truthmark Preview.
|
||||
|
||||
Do not invoke another Truthmark command from here.
|
||||
Truth Preview is read-only and explicit. Do not invoke another Truthmark command from here.
|
||||
|
||||
Read these host-local files in order only as needed:
|
||||
- .github/skills/truthmark-preview/SKILL.md
|
||||
- .github/skills/truthmark-preview/support/procedure.md
|
||||
- .github/skills/truthmark-preview/support/report-template.md
|
||||
- .github/skills/truthmark-preview/support/subagents-and-leases.md
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
|
||||
Invocations: GitHub Copilot /truthmark-preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Return a concise Truth Preview report with these fields:
|
||||
- requested outcome
|
||||
- likely workflow
|
||||
- why this workflow
|
||||
- likely route owner and lane impact
|
||||
- expected write classes
|
||||
- expected target files
|
||||
- suggested subagent use
|
||||
- manual handoff questions
|
||||
- handoff recommendation
|
||||
|
||||
@@ -12,7 +12,5 @@ Read these host-local files in order only as needed:
|
||||
- .github/skills/truthmark-sync/support/procedure.md
|
||||
- .github/skills/truthmark-sync/support/report-template.md
|
||||
- .github/skills/truthmark-sync/support/subagents-and-leases.md
|
||||
- .github/skills/truthmark-sync/helper-manifest.yml
|
||||
- .github/skills/truthmark-sync/support/helper-policy.md
|
||||
|
||||
If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
|
||||
|
||||
@@ -26,5 +26,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- document-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- document report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-document-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -61,6 +61,7 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
@@ -79,12 +80,7 @@ Truthmark hierarchy hints:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
|
||||
- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
|
||||
|
||||
@@ -29,9 +29,6 @@ Evidence checked:
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership.
|
||||
- Truth Preview is read-only; this report is intended, not authorized.
|
||||
- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.
|
||||
- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,53 +0,0 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
@@ -1,43 +0,0 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/routes/areas.md
|
||||
- likely lane impact: engineering-lane
|
||||
- product target docs: none identified
|
||||
- engineering target docs: docs/truthmark/engineering/behaviors/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truthmark/engineering/behaviors/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Copilot custom-agent mode:
|
||||
- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
|
||||
- dispatch read-only project custom agents only: @truth-route-auditor
|
||||
- custom agents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Preview report
|
||||
@@ -19,20 +19,15 @@ Truth Structure is agent-native:
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/routes/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
|
||||
- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
|
||||
- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
|
||||
- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
- use docs/truthmark/product/** for product truth destinations
|
||||
- use docs/truthmark/engineering/** for engineering truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
|
||||
- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
@@ -52,18 +47,12 @@ Do not:
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
@@ -79,10 +68,10 @@ Use these review thresholds as guidance:
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
|
||||
- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
|
||||
- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
|
||||
- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
|
||||
- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
|
||||
- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
@@ -90,21 +79,12 @@ Repair rules:
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair review:
|
||||
- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Evidence checklist:
|
||||
- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
|
||||
- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
|
||||
- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
|
||||
- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
|
||||
@@ -27,5 +27,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- sync-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- sync report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-sync-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -32,78 +32,33 @@ Parent workflow:
|
||||
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
|
||||
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
|
||||
- Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
|
||||
Topology review:
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
|
||||
Topology review and repair:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
|
||||
- run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that require structure repair
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
|
||||
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that required structure repair
|
||||
- do not create another generic truth doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a README.md index
|
||||
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
|
||||
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Evidence checklist:
|
||||
- route-first: map changed functional files to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
|
||||
- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or record unsupported claims for manual handoff
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
|
||||
- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- stop on any unrelated diff caused by the sync step
|
||||
- stop if functional code changed during sync
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
|
||||
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
|
||||
|
||||
@@ -33,9 +33,6 @@ Evidence checked:
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
|
||||
@@ -24,5 +24,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- document-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- document report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-document-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -61,6 +61,7 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
@@ -79,12 +80,7 @@ Truthmark hierarchy hints:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
|
||||
- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
|
||||
|
||||
@@ -29,9 +29,6 @@ Evidence checked:
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership.
|
||||
- Truth Preview is read-only; this report is intended, not authorized.
|
||||
- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.
|
||||
- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,53 +0,0 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
|
||||
- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml, only when present
|
||||
- docs/truthmark/routes/areas.md, first, only when present
|
||||
- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
@@ -1,43 +0,0 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/routes/areas.md
|
||||
- likely lane impact: engineering-lane
|
||||
- product target docs: none identified
|
||||
- engineering target docs: docs/truthmark/engineering/behaviors/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truthmark/engineering/behaviors/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
OpenCode subagent mode:
|
||||
- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents only: @truth-route-auditor
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Preview report
|
||||
@@ -19,20 +19,15 @@ Truth Structure is agent-native:
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/routes/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
|
||||
- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
|
||||
- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
|
||||
- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
- use docs/truthmark/product/** for product truth destinations
|
||||
- use docs/truthmark/engineering/** for engineering truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
|
||||
- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
@@ -52,18 +47,12 @@ Do not:
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
@@ -79,10 +68,10 @@ Use these review thresholds as guidance:
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
|
||||
- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
|
||||
- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
|
||||
- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
|
||||
- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
|
||||
- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
@@ -90,21 +79,12 @@ Repair rules:
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair review:
|
||||
- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Evidence checklist:
|
||||
- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
|
||||
- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
|
||||
- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
|
||||
- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
|
||||
@@ -25,5 +25,3 @@ Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
- helper-manifest.yml — read only when invoking helper validators or validating helper registration
|
||||
- support/helper-policy.md — read only when invoking helper validators or reporting helper status
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- sync-report
|
||||
- <report-file>
|
||||
- --json
|
||||
inputs:
|
||||
- sync report file
|
||||
output: json
|
||||
writes: false
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
- validate
|
||||
- write-lease
|
||||
- <lease-or-report-file>
|
||||
- <changed-files-file>
|
||||
- --json
|
||||
inputs:
|
||||
- lease or worker report yaml
|
||||
- changed file list
|
||||
output: json
|
||||
writes: false
|
||||
fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
@@ -1,23 +0,0 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
|
||||
Runner detection:
|
||||
- Check that the declared Truthmark CLI runner is available before invoking a helper.
|
||||
- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
|
||||
- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
|
||||
- Do not fail the workflow solely because a helper cannot run.
|
||||
|
||||
Available helpers:
|
||||
- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked
|
||||
- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
|
||||
Final reports should include helper status when helpers are declared for this workflow:
|
||||
|
||||
```md
|
||||
Helper scripts:
|
||||
- validate-sync-report: ran, passed
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
```
|
||||
@@ -32,78 +32,33 @@ Parent workflow:
|
||||
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
|
||||
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
|
||||
- Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
|
||||
Topology review:
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
|
||||
Topology review and repair:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
|
||||
- run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that require structure repair
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
|
||||
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that required structure repair
|
||||
- do not create another generic truth doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a README.md index
|
||||
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
|
||||
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Evidence checklist:
|
||||
- route-first: map changed functional files to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
|
||||
- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or record unsupported claims for manual handoff
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
|
||||
Helper status reporting:
|
||||
- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
|
||||
- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
|
||||
- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` and manually validate the report shape.
|
||||
- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`.
|
||||
- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- stop on any unrelated diff caused by the sync step
|
||||
- stop if functional code changed during sync
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
|
||||
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
|
||||
|
||||
@@ -33,9 +33,6 @@ Evidence checked:
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Helper scripts:
|
||||
- validate-write-lease: skipped, no write lease used
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
|
||||
@@ -17,6 +17,6 @@ Agent runtime: host-native skill packages/adapters plus this block; inspect chec
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
@@ -17,6 +17,6 @@ Agent runtime: host-native skill packages/adapters plus this block; inspect chec
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
@@ -17,6 +17,6 @@ Agent runtime: host-native skill packages/adapters plus this block; inspect chec
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
+2
-3
@@ -91,7 +91,6 @@ Beispiele:
|
||||
/truthmark-document
|
||||
/truthmark-structure
|
||||
/truthmark-realize
|
||||
/truthmark-preview
|
||||
/truthmark-check
|
||||
```
|
||||
|
||||
@@ -334,7 +333,6 @@ Sie werden von Agenten oder Agenten-Hosts während der Repository-Arbeit genutzt
|
||||
| Truth Structure | topology-first | Die Standardroute zu breit ist, Ownership mehrere Bereiche umfasst oder Routendateien noch auf Platzhalter zeigen. | Erstellt oder repariert Routing und Starter-Truth-Dokumente. |
|
||||
| Truth Document | implementation-first | Verhalten bereits im Code existiert, aber kanonische Truth-Dokumente fehlen oder schwach sind. | Schreibt nur Truth-Dokumente und Routing. Funktionaler Code darf nicht geändert werden. |
|
||||
| Truth Sync | code-first | Funktionaler Code geändert wurde und zugeordnete Truth-Dokumente vor der Übergabe aktualisiert werden müssen könnten. | Aktualisiert Truth-Dokumente. Funktionaler Code darf von Truth Sync nicht umgeschrieben werden. |
|
||||
| Truth Preview | read-only | Der Agent vor Änderungen wahrscheinliches Routing einschätzen muss. | Liest nur. Autorisiert keine Schreibzugriffe. |
|
||||
| Truth Realize | doc-first | Produkt- oder Architektur-Truth-Dokumente führen und Code daran angepasst werden soll. | Aktualisiert nur Code. Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten. |
|
||||
| Truth Check | audit-first | Ein Reviewer oder Agent die Gesundheit der Repository-Truth auditieren muss. | Auditiert und berichtet. |
|
||||
| Truthmark Portal | presentation-only | Ein Mensch ausdrücklich eine durchsuchbare statische HTML-Portalansicht über Repository-Truth-Dokumente anfordert. | Schreibt generierte nicht-kanonische statische Dateien nur unter dem konfigurierten Portal-Ausgabeverzeichnis. |
|
||||
@@ -408,7 +406,8 @@ Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten.
|
||||
Nutze Truth Preview vor einer Änderung, wenn der Agent wahrscheinliches Routing verstehen muss.
|
||||
|
||||
```text
|
||||
/truthmark-preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen
|
||||
/truthmark-preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen (GitHub Copilot)
|
||||
/truthmark:preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen (Gemini CLI)
|
||||
```
|
||||
|
||||
Truth Preview ist read-only.
|
||||
|
||||
+2
-3
@@ -91,7 +91,6 @@ Ejemplos:
|
||||
/truthmark-document
|
||||
/truthmark-structure
|
||||
/truthmark-realize
|
||||
/truthmark-preview
|
||||
/truthmark-check
|
||||
```
|
||||
|
||||
@@ -334,7 +333,6 @@ Los usan agentes o hosts de agentes durante el trabajo en el repositorio. No son
|
||||
| Truth Structure | topology-first | La ruta predeterminada es demasiado amplia, la propiedad abarca varias áreas o los archivos de rutas siguen apuntando a placeholders. | Crea o repara rutas y documentos de verdad iniciales. |
|
||||
| Truth Document | implementation-first | El comportamiento ya existe en código, pero faltan o son débiles los documentos de verdad canónicos. | Escribe solo documentos de verdad y rutas. No debe cambiar código funcional. |
|
||||
| Truth Sync | code-first | Cambió código funcional y puede que los documentos de verdad asignados deban actualizarse antes de la entrega. | Actualiza documentos de verdad. Truth Sync no debe reescribir código funcional. |
|
||||
| Truth Preview | read-only | El agente necesita previsualizar rutas probables antes de editar. | Solo lee. No autoriza escrituras. |
|
||||
| Truth Realize | doc-first | Documentos de verdad de producto o arquitectura lideran y el código debe actualizarse para coincidir. | Actualiza solo código. El agente no debe editar los documentos de verdad que está realizando. |
|
||||
| Truth Check | audit-first | Un revisor o agente necesita auditar la salud de la verdad del repositorio. | Audita e informa. |
|
||||
| Truthmark Portal | presentation-only | Una persona pide explícitamente un Portal HTML estático navegable sobre los documentos de verdad del repositorio. | Escribe solo archivos estáticos generados no canónicos bajo el directorio de salida Portal configurado. |
|
||||
@@ -408,7 +406,8 @@ El agente no debe editar los documentos de verdad que está realizando.
|
||||
Usa Truth Preview antes de un cambio cuando el agente necesita entender la ruta probable.
|
||||
|
||||
```text
|
||||
/truthmark-preview previsualiza la ruta de verdad probable para cambios en la API de billing
|
||||
/truthmark-preview previsualiza la ruta de verdad probable para cambios en la API de billing (GitHub Copilot)
|
||||
/truthmark:preview previsualiza la ruta de verdad probable para cambios en la API de billing (Gemini CLI)
|
||||
```
|
||||
|
||||
Truth Preview es read-only.
|
||||
|
||||
@@ -91,7 +91,6 @@ Examples:
|
||||
/truthmark-document
|
||||
/truthmark-structure
|
||||
/truthmark-realize
|
||||
/truthmark-preview
|
||||
/truthmark-check
|
||||
```
|
||||
|
||||
@@ -198,7 +197,7 @@ When the agent changes functional code, Truth Sync acts as the finish-time guard
|
||||
| Git-native truth | Keeps repository truth in committed Markdown and config. |
|
||||
| Branch-scoped documentation | Truth moves with the branch instead of living in a private session. |
|
||||
| Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
|
||||
| AI-facing workflows | Gives agents host-native workflows for sync, documentation, structure, preview, realization, and audit. |
|
||||
| AI-facing workflows | Gives agents host-native workflows for sync, documentation, structure, realization, and audit. |
|
||||
| Explicit routing | Maps code areas to canonical truth docs. |
|
||||
| Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
|
||||
| Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
|
||||
@@ -334,7 +333,6 @@ They are used by agents or agent hosts during repository work. They are not top-
|
||||
| Truth Structure | topology-first | The default route is too broad, ownership spans multiple areas, or route files still point at placeholders. | Creates or repairs routing and starter truth docs. |
|
||||
| Truth Document | implementation-first | Behavior already exists in code, but canonical truth docs are missing or weak. | Writes truth docs and routing only. Functional code must not change. |
|
||||
| Truth Sync | code-first | Functional code changed and mapped truth docs may need to be updated before handoff. | Updates truth docs. Functional code must not be rewritten by Truth Sync. |
|
||||
| Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. |
|
||||
| Truth Realize | doc-first | Product or architecture truth docs lead and code should be updated to match. | Updates code only. The agent must not edit the truth docs it is realizing. |
|
||||
| Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. |
|
||||
| Truthmark Portal | presentation-only | A human explicitly asks for a browsable static HTML Portal over repository truth docs. | Writes generated non-canonical static files only under the fixed Portal output directory. |
|
||||
@@ -408,7 +406,8 @@ The agent must not edit the truth docs it is realizing.
|
||||
Use Truth Preview before a change when the agent needs to understand likely routing.
|
||||
|
||||
```text
|
||||
/truthmark-preview preview the likely truth routing for changes to the billing API
|
||||
/truthmark-preview preview the likely truth routing for changes to the billing API (GitHub Copilot)
|
||||
/truthmark:preview preview the likely truth routing for changes to the billing API (Gemini CLI)
|
||||
```
|
||||
|
||||
Truth Preview is read-only.
|
||||
|
||||
+2
-3
@@ -91,7 +91,6 @@ Truthmark устанавливает host-native skills, prompts, commands, уп
|
||||
/truthmark-document
|
||||
/truthmark-structure
|
||||
/truthmark-realize
|
||||
/truthmark-preview
|
||||
/truthmark-check
|
||||
```
|
||||
|
||||
@@ -334,7 +333,6 @@ truthmark init
|
||||
| Truth Structure | topology-first | Стандартный маршрут слишком широкий, владение охватывает несколько областей или файлы маршрутов все еще указывают на placeholders. | Создает или исправляет маршрутизацию и стартовые документы истины. |
|
||||
| Truth Document | implementation-first | Поведение уже есть в коде, но канонические документы истины отсутствуют или слабы. | Пишет только документы истины и маршрутизацию. Функциональный код менять нельзя. |
|
||||
| Truth Sync | code-first | Функциональный код изменился, и сопоставленные документы истины могут потребовать обновления перед передачей. | Обновляет документы истины. Truth Sync не должен переписывать функциональный код. |
|
||||
| Truth Preview | read-only | Агенту нужно предварительно понять вероятную маршрутизацию перед правками. | Только чтение. Не авторизует записи. |
|
||||
| Truth Realize | doc-first | Продуктовые или архитектурные документы истины ведут, и код нужно обновить под них. | Обновляет только код. Агент не должен редактировать документы истины, которые реализует. |
|
||||
| Truth Check | audit-first | Ревьюеру или агенту нужно проверить актуальность истины репозитория. | Аудитирует и сообщает. |
|
||||
| Truthmark Portal | presentation-only | Человек явно просит доступный для просмотра статический HTML Portal по документам истины репозитория. | Пишет только сгенерированные неканонические статические файлы в настроенную директорию вывода Portal. |
|
||||
@@ -408,7 +406,8 @@ Truth Realize работает doc-first.
|
||||
Используйте Truth Preview перед изменением, когда агенту нужно понять вероятную маршрутизацию.
|
||||
|
||||
```text
|
||||
/truthmark-preview покажи вероятный truth routing для изменений billing API
|
||||
/truthmark-preview покажи вероятный truth routing для изменений billing API (GitHub Copilot)
|
||||
/truthmark:preview покажи вероятный truth routing для изменений billing API (Gemini CLI)
|
||||
```
|
||||
|
||||
Truth Preview работает read-only.
|
||||
|
||||
+2
-3
@@ -91,7 +91,6 @@ Truthmark 会安装宿主原生的技能、提示、命令、受管指令块和
|
||||
/truthmark-document
|
||||
/truthmark-structure
|
||||
/truthmark-realize
|
||||
/truthmark-preview
|
||||
/truthmark-check
|
||||
```
|
||||
|
||||
@@ -334,7 +333,6 @@ truthmark init
|
||||
| Truth Structure | topology-first | 默认路由过宽、所有权跨多个区域，或路由文件仍指向占位内容。 | 创建或修复路由和起始事实文档。 |
|
||||
| Truth Document | implementation-first | 行为已经存在于代码中，但规范事实文档缺失或薄弱。 | 只写事实文档和路由。不能改变功能代码。 |
|
||||
| Truth Sync | code-first | 功能代码已变更，已映射事实文档可能需要在交接前更新。 | 更新事实文档。Truth Sync 不能重写功能代码。 |
|
||||
| Truth Preview | read-only | 代理需要在编辑前预览可能的路由。 | 只读。不授权写入。 |
|
||||
| Truth Realize | doc-first | 产品或架构事实文档在前，代码应更新以匹配它们。 | 只更新代码。代理不能编辑它正在实现的事实文档。 |
|
||||
| Truth Check | audit-first | 审查者或代理需要审计仓库事实健康状况。 | 审计并报告。 |
|
||||
| Truthmark Portal | presentation-only | 人类明确要求为仓库事实文档生成可浏览的静态 HTML Portal。 | 只在配置的 Portal 输出目录下写入生成的非规范静态文件。 |
|
||||
@@ -408,7 +406,8 @@ Truth Realize 是 doc-first。
|
||||
当代理需要在变更前理解可能的路由时，使用 Truth Preview。
|
||||
|
||||
```text
|
||||
/truthmark-preview 预览 billing API 变更的可能事实路由
|
||||
/truthmark-preview 预览 billing API 变更的可能事实路由 (GitHub Copilot)
|
||||
/truthmark:preview 预览 billing API 变更的可能事实路由 (Gemini CLI)
|
||||
```
|
||||
|
||||
Truth Preview 是 read-only。
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-architecture
|
||||
last_reviewed: 2026-06-14
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Architecture Overview
|
||||
@@ -14,6 +14,12 @@ This doc owns the current source-level architecture of Truthmark as a workflow i
|
||||
|
||||
It covers CLI handlers, config loading, routing, checks, generation, repository intelligence, and workflow-surface rendering.
|
||||
|
||||
## System Role
|
||||
|
||||
Truthmark is a repository-local documentation workflow injector.
|
||||
|
||||
It turns checkout evidence, route metadata, and source renderers into committed truth docs, checks, and host-native workflow files.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
Truthmark is a local CLI and generated-surface renderer. It reads checkout files, normalizes configuration, parses route files, emits diagnostics, and writes configured workflow surfaces during init.
|
||||
@@ -35,6 +41,25 @@ Truthmark is a local CLI and generated-surface renderer. It reads checkout files
|
||||
- Workflow manifest and generated surface renderer
|
||||
- RepoIndex, RouteMap, ImpactSet, and WorkflowState/action-context builders
|
||||
|
||||
## Data And Control Flow
|
||||
|
||||
- CLI commands load config and repository paths from the active checkout.
|
||||
- Route parsing builds area ownership and truth-doc relationships from route markdown files.
|
||||
- Check and index flows inspect committed files and emit diagnostics or compact repository metadata.
|
||||
- Init flows render templates and generated surfaces back into the checkout.
|
||||
|
||||
## Ownership
|
||||
|
||||
Architecture ownership follows the source modules and routed truth docs listed in Source References.
|
||||
|
||||
Workflow-surface architecture is owned by the installed-workflows route area.
|
||||
|
||||
## Cross-Cutting Constraints
|
||||
|
||||
- Truthmark must remain usable from committed repository files without a live daemon.
|
||||
- Generated workflow surfaces are refreshable artifacts; source renderers remain the generation authority.
|
||||
- Product and engineering truth remain separate lanes.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/lane-separated-truth.md`
|
||||
@@ -43,6 +68,15 @@ Truthmark is a local CLI and generated-surface renderer. It reads checkout files
|
||||
|
||||
- Decision (2026-06-14): Architecture docs describe current repository realization and do not redefine product promises.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping architecture truth source-backed and lane-scoped prevents generated agent workflow guidance from becoming an alternate product authority.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc does not own product capability promises.
|
||||
- This doc does not describe every command contract in detail; contract docs own public surfaces.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update when module boundaries, generated-surface ownership, or command architecture changes.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-15
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Check Diagnostics
|
||||
@@ -33,6 +33,17 @@ Product truth doc structure validation enforces the `product-capability` shape.
|
||||
- Duplicate route entries for the same path, kind, and lane merge `realized_by`, `realizes`, and `depends_on` by unique sorted set.
|
||||
- Check reports structure and evidence only; it does not judge product strategy.
|
||||
|
||||
## Flows And States
|
||||
|
||||
- Check loads config and routed truth docs from the active checkout.
|
||||
- It runs structural, generated-surface, routing, traceability, and truth-doc checks.
|
||||
- It reports diagnostics and scorecard dimensions without mutating files.
|
||||
|
||||
## Contracts
|
||||
|
||||
- Diagnostic names, severities, and JSON shape are owned by contract truth.
|
||||
- Route relationship validation is described in `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/lane-separated-truth.md`
|
||||
@@ -44,6 +55,16 @@ Product truth doc structure validation enforces the `product-capability` shape.
|
||||
- Decision (2026-06-15): Duplicate route entries with the same path, kind, and lane are an additive relationship model; divergent relationship arrays merge instead of erroring so area-local route entries do not have to repeat the full relationship closure.
|
||||
- Decision (2026-06-15): `realized_by` and `realizes` route metadata is route-local navigation metadata, not a canonical global graph, so check validates target existence and lane compatibility without requiring reciprocal edges.
|
||||
|
||||
## Rationale
|
||||
|
||||
Check keeps diagnostics local to repository truth and route metadata so agents can repair docs without treating Truthmark as a hidden graph database.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Check does not execute workflow agents.
|
||||
- Check does not rewrite truth docs or route files.
|
||||
- Check does not judge product strategy beyond structure and traceability rules.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update when check categories, severity rules, lane audit behavior, or product kind section requirements change.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-17
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Init And Scaffold
|
||||
@@ -16,9 +16,82 @@ It covers config defaults, lane root creation, template files, and starter route
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
Defaults derive all scaffold paths from `truthmark.workspace`. Routes are fixed at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`; the default scaffolded route area is `repository`; max route delegation depth is `1`; product truth is fixed at `<workspace>/product`; engineering truth is fixed at `<workspace>/engineering`; editable truth templates are fixed at `<workspace>/templates`. Template filenames match `truth_kind` values directly: `product-capability.md`, `engineering-behavior.md`, `engineering-contract.md`, `engineering-architecture.md`, `engineering-workflow.md`, `engineering-operations.md`, and `engineering-test-behavior.md`. Generated truth-doc frontmatter includes `truth_kind` and does not include `doc_type` or `truth_lane`.
|
||||
Scaffold paths derive from `truthmark.workspace`:
|
||||
|
||||
Init seeds the broad default `repository` route as provisional bootstrap routing, not as normal behavior ownership. The route still maps `src/**` so a fresh repository is routeable, but it points at `engineering/repository/bootstrap-routing.md` as an `engineering-workflow` handoff that tells agents to run Truth Structure before normal Truth Sync when real code touches only the broad default route. Init does not create `engineering/repository/overview.md` from `engineering-behavior.md`; behavior truth should be created in bounded areas after ownership is known. Downstream product truth uses the `product-capability` template only. Capability docs own a single user-visible capability promise, users/value, scope including boundary constraints and adjacent systems, current product behavior, acceptance criteria, decisions, realization links, and non-goals.
|
||||
- Routes live at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`.
|
||||
- Product truth lives at `<workspace>/product`.
|
||||
- Engineering truth lives at `<workspace>/engineering`.
|
||||
- Editable truth templates live at `<workspace>/templates`.
|
||||
- The default scaffolded route area is `repository`.
|
||||
- Max route delegation depth is `1`.
|
||||
|
||||
Fresh configs do not assume a host platform:
|
||||
|
||||
- `platforms` is omitted by default.
|
||||
- Host-specific workflow surfaces are generated only after maintainers explicitly list Codex, OpenCode, Claude Code, GitHub Copilot, or Gemini CLI.
|
||||
|
||||
Editable truth template filenames match `truth_kind` values directly:
|
||||
|
||||
- `product-capability.md`
|
||||
- `engineering-behavior.md`
|
||||
- `engineering-contract.md`
|
||||
- `engineering-architecture.md`
|
||||
- `engineering-workflow.md`
|
||||
- `engineering-operations.md`
|
||||
- `engineering-test-behavior.md`
|
||||
|
||||
Generated truth-doc frontmatter includes `truth_kind`.
|
||||
|
||||
Generated truth-doc frontmatter does not include `doc_type` or `truth_lane`.
|
||||
|
||||
`truthmark init` also removes retired generated-surface artifacts under host skill roots (for example `truthmark-preview` package files and legacy `helper-manifest.yml`/`support/helper-policy.md`) when those paths are no longer part of current generated output.
|
||||
|
||||
Generated truth-doc templates keep kind-specific and section-specific authoring comments in the template files.
|
||||
|
||||
Global diff-friendly authoring style lives in the Truth Document workflow procedure rather than in every template preamble:
|
||||
|
||||
- Prefer one durable claim per bullet or line.
|
||||
- Keep paragraphs to one or two short sentences.
|
||||
- Use bullets or tables for rules, criteria, fields, files, and lists.
|
||||
|
||||
Init seeds the broad default `repository` route as provisional bootstrap routing, not as normal behavior ownership:
|
||||
|
||||
- The route still maps `src/**` so a fresh repository is routeable.
|
||||
- The route points at `engineering/repository/bootstrap-routing.md` as an `engineering-workflow` handoff.
|
||||
- The handoff tells agents to run Truth Structure before normal Truth Sync when real code touches only the broad default route.
|
||||
- Init does not create `engineering/repository/overview.md` from `engineering-behavior.md`.
|
||||
- Behavior truth should be created in bounded areas after ownership is known.
|
||||
|
||||
Downstream product truth uses the `product-capability` template only.
|
||||
|
||||
Capability docs own:
|
||||
|
||||
- a single user-visible capability promise
|
||||
- users and value
|
||||
- scope including boundary constraints and adjacent systems
|
||||
- current product behavior
|
||||
- acceptance criteria
|
||||
- decisions
|
||||
- realization links
|
||||
- non-goals
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Scaffolded paths derive from `truthmark.workspace`.
|
||||
- Template filenames match `truth_kind` values.
|
||||
- Fresh configs do not assume any AI host platform.
|
||||
- Global prose style guidance belongs in writer-facing workflow procedures, not every truth-doc template preamble.
|
||||
|
||||
## Flows And States
|
||||
|
||||
- `truthmark init` creates or refreshes workspace scaffold files.
|
||||
- It renders current templates and generated host surfaces from source renderers.
|
||||
- It removes retired generated-surface artifacts that are no longer part of current generated output.
|
||||
|
||||
## Contracts
|
||||
|
||||
- Config normalization and route metadata contracts are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.
|
||||
- Generated host-surface contracts are owned by `docs/truthmark/engineering/contracts/generated-host-surfaces.md`.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
@@ -30,6 +103,19 @@ Init seeds the broad default `repository` route as provisional bootstrap routing
|
||||
- Decision (2026-06-14): Editable template filenames match `truth_kind` values directly so generated docs do not point agents at legacy `*-doc.md` names.
|
||||
- Decision (2026-06-14): Init scaffolds routes, templates, product truth, and engineering truth at fixed workspace-derived paths rather than accepting route or template roots from config.
|
||||
- Decision (2026-06-17): The default broad `repository` route is provisional bootstrap state; init creates a compact `bootstrap-routing.md` workflow handoff instead of a catch-all behavior overview so agents run Truth Structure before normal Sync on real touched code.
|
||||
- Decision (2026-06-18): Fresh configs omit `platforms` by default. Truthmark does not infer Codex, OpenCode, or any other host from a fresh checkout; host-native workflow surfaces require explicit platform configuration.
|
||||
|
||||
## Rationale
|
||||
|
||||
Fixed workspace-derived scaffold paths keep Truthmark predictable while route files provide the semantic ownership layer.
|
||||
|
||||
Keeping templates kind-specific and moving global prose style into workflow guidance reduces generated-template bloat.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Init does not infer a preferred agent host.
|
||||
- Init does not create behavior truth for unknown code ownership beyond the provisional bootstrap routing handoff.
|
||||
- Init does not maintain a legacy `docs/truthmark/truth` tree.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
@@ -41,5 +127,3 @@ Update when init writes new files, changes default paths, changes template filen
|
||||
- ../../../../src/init/hierarchy.ts
|
||||
- ../../../../src/templates/init-files.ts
|
||||
- ../../../../tests/init/init-instructions.test.ts
|
||||
- ../../../../tests/templates/init-files.test.ts
|
||||
- ../../../../tests/integration/init-check-workflow.test.ts
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-contract
|
||||
last_reviewed: 2026-06-17
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Config, Route, And Check Contracts
|
||||
@@ -16,7 +16,56 @@ It covers config normalization, route `truth_documents` metadata, diagnostic cat
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
Default config exposes `truthmark.workspace` and `truthmark.generated.portal.enabled`; it does not expose route layout, template layout, or truth lane roots as knobs. Routes are fixed at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`, the default area is the product invariant `repository`, max delegation depth is the product invariant `1`, templates are fixed at `<workspace>/templates`, product truth is fixed at `<workspace>/product`, and engineering truth is fixed at `<workspace>/engineering`. User-provided `truthmark.routes`, `truthmark.templates`, or `truthmark.truth` blocks are rejected as unsupported additional properties. Route entries can declare `kind`, optional `lane`, `realized_by`, `realizes`, and `depends_on`; product `realized_by` and engineering `realizes` links are valid when their targets exist and point to the opposite lane, without requiring reciprocal declarations. Duplicate route entries for the same path, kind, and lane merge relationship metadata for `realized_by`, `realizes`, and `depends_on` by unique sorted set before validation and RouteMap output; conflicting duplicate kinds or lanes are reported as area-index errors. The public ContextPack command surface is retired. Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for an advisory workflow card, write-boundary suggestions, suggested truth docs, review checklist, evidence prompts, optional helper commands, open questions, skipped-helper status, diagnostics, next steps, and compact affected-test guidance, and `truthmark impact --base <ref> --json` for branch-diff routing. These replacement JSON outputs emit paths, metadata, diagnostics, and command arrays only; they do not embed source-file or truth-doc body contents.
|
||||
Default config exposes optional `platforms`, `truthmark.workspace`, and `truthmark.generated.portal.enabled`.
|
||||
|
||||
Default config does not expose route layout, template layout, or truth lane roots as knobs.
|
||||
|
||||
When `platforms` is omitted, normalized config defaults to an empty platform list:
|
||||
|
||||
- No host-specific workflow surfaces are generated by default.
|
||||
- Codex surfaces are generated only when `platforms` explicitly includes `codex`.
|
||||
- Multi-host generated surfaces are explicit opt-in config.
|
||||
|
||||
Fixed workspace-derived paths and invariants:
|
||||
|
||||
- Routes are fixed at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`.
|
||||
- The default area is the product invariant `repository`.
|
||||
- Max delegation depth is the product invariant `1`.
|
||||
- Templates are fixed at `<workspace>/templates`.
|
||||
- Product truth is fixed at `<workspace>/product`.
|
||||
- Engineering truth is fixed at `<workspace>/engineering`.
|
||||
|
||||
User-provided `truthmark.routes`, `truthmark.templates`, or `truthmark.truth` blocks are rejected as unsupported additional properties.
|
||||
|
||||
Route entries can declare `kind`, optional `lane`, `realized_by`, `realizes`, and `depends_on`.
|
||||
|
||||
Product `realized_by` and engineering `realizes` links are valid when their targets exist and point to the opposite lane, without requiring reciprocal declarations.
|
||||
|
||||
Duplicate route entries for the same path, kind, and lane merge relationship metadata for `realized_by`, `realizes`, and `depends_on` by unique sorted set before validation and RouteMap output.
|
||||
|
||||
Conflicting duplicate kinds or lanes are reported as area-index errors.
|
||||
|
||||
The public ContextPack command surface is retired.
|
||||
|
||||
Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for:
|
||||
|
||||
- an advisory workflow card
|
||||
- write-boundary suggestions
|
||||
- suggested truth docs
|
||||
- review checklist
|
||||
- evidence prompts
|
||||
- optional helper commands
|
||||
- open questions
|
||||
- skipped-helper status
|
||||
- diagnostics
|
||||
- next steps
|
||||
- compact affected-test guidance
|
||||
|
||||
Agents use `truthmark impact --base <ref> --json` for branch-diff routing.
|
||||
|
||||
These replacement JSON outputs emit paths, metadata, diagnostics, and command arrays only.
|
||||
|
||||
They do not embed source-file or truth-doc body contents.
|
||||
|
||||
## Contract Surface
|
||||
|
||||
@@ -35,16 +84,30 @@ Default config exposes `truthmark.workspace` and `truthmark.generated.portal.ena
|
||||
|
||||
## Outputs
|
||||
|
||||
- Normalized config includes an empty `platforms` list when the field is omitted; host-specific surfaces require explicit platform entries.
|
||||
- Normalized config paths for fixed route, template, product truth, engineering truth, and Portal locations derived from `truthmark.workspace`
|
||||
- RouteMap data preserving lane and relationship metadata, plus RepoIndex data preserving derived doc type and lane metadata
|
||||
- WorkflowState data preserving workflow write boundaries and compact test guidance without file contents
|
||||
- ImpactSet data preserving branch-diff routing and affected tests without file contents
|
||||
- Diagnostics including `lane-shape`, `lane-drift`, and `traceability`
|
||||
|
||||
## Errors And Diagnostics
|
||||
|
||||
- Unsupported config fields are validation diagnostics.
|
||||
- Conflicting duplicate route kinds or lanes are area-index errors.
|
||||
- Missing or stale truth-doc relationships are traceability diagnostics.
|
||||
- Unmapped functional-code changes are freshness or routing diagnostics depending on command context.
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
The target model is lane-first and does not use `docs/truthmark/truth` as the canonical scaffold target.
|
||||
|
||||
## Versioning And Migration
|
||||
|
||||
- Config files use `version: 2`.
|
||||
- Removed public command surfaces, such as standalone ContextPack, are hard-removed rather than preserved as aliases in this branch.
|
||||
- Legacy canonical truth roots are migrated into product and engineering lane roots.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/lane-separated-truth.md`
|
||||
@@ -57,6 +120,17 @@ The target model is lane-first and does not use `docs/truthmark/truth` as the ca
|
||||
- Decision (2026-06-15): Duplicate route relationship metadata is additive for matching path, kind, and lane entries; kind and lane conflicts remain hard validation errors.
|
||||
- Decision (2026-06-15): Route relationships are route-local metadata; checks validate relationship targets for existence and lane compatibility without requiring a reciprocal global graph edge.
|
||||
- Decision (2026-06-15): ContextPack is folded into workflow status and impact; the standalone `truthmark context` command is hard-removed from the public CLI.
|
||||
- Decision (2026-06-18): Omitted `platforms` normalize to an empty platform list; all host-specific generated surfaces, including Codex, are explicit opt-in config.
|
||||
|
||||
## Rationale
|
||||
|
||||
The public contract exposes compact routing and workflow metadata instead of file-body packets so agents can choose bounded reads from the checkout.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This contract does not define language-semantic import graphs or symbol indexes.
|
||||
- This contract does not preserve legacy ContextPack aliases.
|
||||
- This contract does not make route relationships a required reciprocal global graph.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-contract
|
||||
last_reviewed: 2026-06-15
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Generated Host Surfaces
|
||||
@@ -12,11 +12,21 @@ This doc owns the current generated host surface contract.
|
||||
|
||||
## Scope
|
||||
|
||||
It covers configured platform output paths, generated workflow files, managed instruction blocks, and helper metadata.
|
||||
It covers configured platform output paths, generated workflow files, managed instruction blocks, and compact optional validation commands.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
Truthmark renders workflow surfaces for configured platforms and leaves already committed files in place when platforms are removed from config. Host skill packages carry canonical workflow entrypoints plus support files for full procedures, report templates, subagent guidance, and helper policy. GitHub Copilot prompt files and Gemini command files are lightweight workflow adapters: they identify the current host entrypoint, tell the agent not to invoke another Truthmark command from inside that entrypoint, point only to host-local skill package files, and use direct checkout inspection as fallback instead of duplicating full workflow bodies.
|
||||
Truthmark renders workflow surfaces only for configured platforms. Legacy package artifacts are explicitly retired.
|
||||
|
||||
- `truthmark init` removes obsolete generated files that are no longer in `renderGeneratedSurfaces(...)`, including `truthmark-preview` package contents and legacy `helper-manifest.yml` and `support/helper-policy.md` files under host skill roots.
|
||||
- `truthmark check` reports missing, stale, or obsolete generated surfaces when render outputs and committed files differ.
|
||||
|
||||
When `platforms` is omitted, fresh config does not assume a host platform; `truthmark init` still maintains instruction targets, but host-specific skill/prompt/command surfaces are opt-in through explicit `platforms` entries.
|
||||
Host skill packages carry canonical workflow entrypoints plus support files for full procedures, report templates, and subagent/lease guidance when the workflow uses subagents; generated helper manifest and helper policy files are intentionally not emitted.
|
||||
GitHub Copilot prompt files and Gemini command files are lightweight workflow adapters: most point to the current host entrypoint and tell the agent not to invoke another Truthmark command from inside that entrypoint.
|
||||
Truth Preview remains a read-only prompt/command body for Copilot and Gemini instead of a standalone host skill package.
|
||||
|
||||
Preview prompt/command bodies stay compact by listing the report fields instead of embedding the full markdown report example.
|
||||
|
||||
## Contract Surface
|
||||
|
||||
@@ -32,9 +42,26 @@ Truthmark renders workflow surfaces for configured platforms and leaves already
|
||||
## Outputs
|
||||
|
||||
- Host-native workflow skill packages and compact prompt/command adapters
|
||||
- Optional helper manifests
|
||||
- Procedure, report-template, and subagent/lease support files only when a workflow needs them
|
||||
- Managed instruction blocks with non-versioned refresh guidance
|
||||
|
||||
## Errors And Diagnostics
|
||||
|
||||
- `truthmark check` reports missing, stale, or obsolete generated surfaces.
|
||||
- `truthmark init` removes retired managed artifacts when they are no longer rendered.
|
||||
- Generated-surface freshness uses rendered-content comparison rather than package-version markers.
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
- Host-specific workflow files are generated only for configured platforms.
|
||||
- Thin adapters are reserved for prompt, command, and top-level instruction surfaces.
|
||||
- Host skill directories remain native generated packages with colocated support files when the host consumes skill-directory resources.
|
||||
|
||||
## Versioning And Migration
|
||||
|
||||
- Retired generated files are removed during init instead of remaining as stale runtime guidance.
|
||||
- Generated surfaces use non-versioned refresh wording; package versions are not runtime authority.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/agent-native-workflow-injection.md`
|
||||
@@ -44,10 +71,25 @@ Truthmark renders workflow surfaces for configured platforms and leaves already
|
||||
- Decision (2026-06-14): Generated surfaces must preserve Truthmark as a workflow injector, not a runtime authority.
|
||||
- Decision (2026-06-15): GitHub Copilot prompt files and Gemini command files stay compact workflow adapters when a host skill package exists; canonical workflow bodies remain in generated skill support files.
|
||||
- Decision (2026-06-15): GitHub Copilot prompt files and Gemini command files must not embed cross-host Truthmark invocation lists; those lists belong in human-facing docs or skill metadata, not adapter bodies.
|
||||
- Decision (2026-06-18): Fresh configs do not assume Codex, OpenCode, or any other host platform. Host-specific surfaces are opt-in through explicit `platforms` entries.
|
||||
- Decision (2026-06-18): Generated helper manifest and helper policy files are removed; optional validation commands remain in workflow metadata and report validation accepts manual fallback evidence.
|
||||
- Decision (2026-06-18): Truth Preview stays a read-only Copilot/Gemini prompt-command surface instead of a standalone generated skill package.
|
||||
- Decision (2026-06-20): Preview adapters list concise report fields rather than embedding the full markdown report example, keeping Preview thin while preserving report shape.
|
||||
- Decision (2026-06-18): Truth Sync keeps bounded topology repair in the finish-time path; Sync runs or applies Truth Structure-style repair when safe and scoped, and hands off only unsafe or ambiguous topology work.
|
||||
|
||||
## Rationale
|
||||
|
||||
Host-native skill packages preserve progressive disclosure for agents that package skill directories, while compact adapters prevent prompt and command surfaces from duplicating full workflow bodies.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Generated surfaces are not a live daemon or orchestration layer.
|
||||
- Preview is not a standalone write-capable workflow package.
|
||||
- Optional validators do not require generated helper manifest files.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update when platform paths, supported hosts, helper manifests, or managed block content changes.
|
||||
Update when platform paths, supported hosts, optional validation commands, or managed block content changes.
|
||||
|
||||
## Source References
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-operations
|
||||
last_reviewed: 2026-06-14
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Release Automation
|
||||
@@ -27,6 +27,27 @@ Release and CI behavior is implemented through checked-in GitHub workflow files
|
||||
|
||||
Automation runs in GitHub Actions. There is no Truthmark daemon or persistent runtime service.
|
||||
|
||||
## Configuration
|
||||
|
||||
- GitHub workflow YAML files define CI and release triggers.
|
||||
- `src/templates/github-action.ts` owns generated GitHub Action template behavior.
|
||||
|
||||
## Permissions
|
||||
|
||||
Permissions are owned by the checked-in GitHub workflow and action template definitions.
|
||||
|
||||
This doc does not add permissions beyond those source files.
|
||||
|
||||
## Deployment And Rollback
|
||||
|
||||
- Workflow changes deploy when repository workflow files are committed to the target branch.
|
||||
- Rollback is a normal Git revert or follow-up workflow-file change.
|
||||
|
||||
## Availability And Observability
|
||||
|
||||
- GitHub Actions provides run status and logs.
|
||||
- Truthmark has no separate release automation runtime to monitor.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- None.
|
||||
@@ -35,6 +56,15 @@ Automation runs in GitHub Actions. There is no Truthmark daemon or persistent ru
|
||||
|
||||
- Decision (2026-06-14): Release automation truth is engineering/operational truth because it describes current repository mechanics.
|
||||
|
||||
## Rationale
|
||||
|
||||
Release automation is documented as operations truth because failures, permissions, and rollback are repository mechanics rather than product capability promises.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc does not define package versioning policy.
|
||||
- This doc does not own npm publishing credentials or external registry behavior.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update when CI triggers, release prerequisites, publish steps, or action templates change.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-05-30
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Repository Overview
|
||||
@@ -79,15 +79,6 @@ Explain decisions that shape behavior, boundaries, rejected alternatives, or mig
|
||||
|
||||
- Decision (2026-06-14): Truth README files are indexes; behavior truth belongs in bounded leaf docs.
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active decisions only, dated inline when added or changed.
|
||||
Explain decisions that shape behavior, boundaries, rejected alternatives, or migration constraints; replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-17
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Repository Intelligence
|
||||
@@ -28,6 +28,24 @@ Evidence validation checks repository containment, referenced file or glob exist
|
||||
|
||||
Generated-surface diagnostics are checkout-derived repository intelligence for the installed workflow runtime. `truthmark check` compares rendered generated surfaces with committed files and reports missing or stale generated host-native skill package files so skill-directory resources stay colocated with `SKILL.md`.
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Repository intelligence is advisory checkout context, not hidden memory or off-repo authority.
|
||||
- WorkflowState and ImpactSet expose paths, metadata, diagnostics, and checklists without embedding source-file or truth-doc bodies.
|
||||
- Route relationships remain route-local metadata.
|
||||
|
||||
## Flows And States
|
||||
|
||||
- RepoIndex and RouteMap are built from committed repository files.
|
||||
- ImpactSet maps branch changes to affected routes, truth docs, and tests.
|
||||
- WorkflowState packages workflow-specific handoff data and open questions.
|
||||
- Evidence validation checks referenced paths, globs, line spans, and hashes.
|
||||
|
||||
## Contracts
|
||||
|
||||
- Public JSON shapes are contract truth owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.
|
||||
- Generated-surface freshness behavior is contract truth owned by `docs/truthmark/engineering/contracts/generated-host-surfaces.md`.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/lane-separated-truth.md`
|
||||
@@ -42,6 +60,16 @@ Generated-surface diagnostics are checkout-derived repository intelligence for t
|
||||
- Decision (2026-06-16): Sync Intent is a transient report-section checklist exposed through workflow/report surfaces and WorkflowState report sections; it is not repository-intelligence state or a persisted plan.
|
||||
- Decision (2026-06-17): Generated-surface freshness includes host-native package diagnostics; these diagnostics are review output and do not add hooks, live services, duplicate workflow packages, or mandatory workflow preflight execution.
|
||||
|
||||
## Rationale
|
||||
|
||||
Compact repository intelligence saves agent context by pointing to likely routes and evidence without replacing direct checkout inspection.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Repository intelligence does not maintain language-specific semantic indexes.
|
||||
- Repository intelligence does not emit complete file contents.
|
||||
- WorkflowState does not execute workflows or decide final correctness.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update when index, route-map, impact, evidence, freshness, or workflow-state output changes.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-17
|
||||
last_reviewed: 2026-06-20
|
||||
---
|
||||
|
||||
# Installed Workflow Runtime
|
||||
@@ -12,13 +12,128 @@ This doc describes how the repository currently realizes host-native Truthmark w
|
||||
|
||||
## Scope
|
||||
|
||||
It owns generated workflow runtime behavior, managed instruction blocks, helper metadata, and direct-checkout fallback rules.
|
||||
It owns generated workflow runtime behavior, managed instruction blocks, optional validation commands, and direct-checkout fallback rules.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
The source manifest and renderers are the package-generation authority; `truthmark init` projects that source into host-native workflow files. Generated host skill directories are native skill packages: their `SKILL.md` files keep package-local `support/procedure.md`, `support/report-template.md`, subagent/lease guidance, helper manifests, and helper policy files so hosts that package skill-directory resources do not depend on arbitrary cross-repository file reads. Truthmark does not emit a separate `.truthmark/agent/` workflow copy because host skill packages are the runtime surfaces agents actually load; duplicating them under `.truthmark/agent/` would add repository docs with no active host consumer. GitHub Copilot prompts, Gemini commands, and top-level managed instruction blocks stay thin and point to host-native workflow entrypoints rather than embedding full workflow bodies. Generated-surface checks report missing or stale host-native skill package files.
|
||||
The source manifest and renderers are the package-generation authority.
|
||||
|
||||
Workflow manifest entries use review-oriented questions that surface as a WorkflowState `reviewChecklist`, while evidence-oriented entries surface as `evidencePrompts`. Generated GitHub Copilot prompts and Gemini commands act as compact host entrypoint adapters: they direct the current invocation to host-local skill package files and explicitly avoid dispatching another Truthmark command rather than embedding duplicate workflow bodies or cross-host invocation lists. Truth Sync generated procedures use a product-truth decision before canonical truth writes: update or route product truth only when a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed; otherwise internal implementation changes default to engineering truth. Truth Sync also performs decision context capture from the current task conversation: agents review user-provided decisions, rationale, constraints, tradeoffs, rejection reasons, and scope boundaries, carry that context into Sync Intent, place it in the correct product or engineering truth lane when supported, and report whether it was placed, skipped because none was provided, or needs manual handoff. Other write-capable truth workflows preserve lane-specific classification before canonical truth writes, while read-only Preview and Check surfaces classify lane ownership for reporting without write-authorizing phrasing. The manual Truth Realize prompt path uses Realize-specific lane guidance: read product truth as requirements, read engineering truth as implementation context, and do not write truth docs or truth routing while realizing docs into code. Truth Preview keeps route selection thin by reading the root route index first and then only child route files relevant to the selected scope or changed paths, and reports unresolved manual handoff questions rather than final correctness. Truth Check and read-only route auditors use route-first bounded inspection for lane and cross-lane relationship checks: narrow audits stay within the routed area plus directly linked counterpart docs, root-wide health first builds a route-map/index from route files, and missing product links for user-visible engineering docs are second-pass review diagnostics rather than default full-document reads. Truth Sync generated procedures and report templates include a transient Sync Intent checkpoint that records changed code reviewed, affected route/truth owner, target truth docs, intended update, evidence to verify, user-provided decisions/rationale, no-update-needed rationale, and blockers before canonical truth writes. Optional CLI repository-intelligence helpers are compact advisory cards: workflow status reports affected files, likely route owners, suggested truth docs, open questions, skipped helper status, and compact write-boundary suggestions; impact exposes branch-diff routing data; neither helper emits source-file or truth-doc body contents. Truth Sync workflow status separates impacted primary truth docs from candidate stale truth docs and route files so stale repository-truth correction remains available without making every indexed doc look like the starting scope.
|
||||
`truthmark init` projects source renderers into configured host-native workflow files.
|
||||
|
||||
Fresh configs do not assume a host platform:
|
||||
|
||||
- Host-specific surfaces are generated only when `.truthmark/config.yml` explicitly lists platforms such as Codex, OpenCode, Claude Code, GitHub Copilot, or Gemini CLI.
|
||||
|
||||
Generated host skill directories are native skill packages for write-capable and audit workflows:
|
||||
|
||||
- `SKILL.md` files keep package-local `support/procedure.md` and `support/report-template.md`.
|
||||
- Subagent and lease guidance is kept only when the workflow uses subagents.
|
||||
- Hosts that package skill-directory resources do not depend on arbitrary cross-repository file reads.
|
||||
|
||||
Generated helper manifests and helper policy support files are not emitted:
|
||||
|
||||
- Optional validation commands stay in workflow metadata.
|
||||
- Report validation accepts manual fallback evidence.
|
||||
|
||||
Truth Preview is read-only and explicit:
|
||||
|
||||
- Copilot and Gemini receive prompt-command bodies instead of standalone skill packages.
|
||||
- Preview prompt-command bodies include a compact field checklist rather than embedding the full markdown report example.
|
||||
|
||||
Truthmark does not emit a separate `.truthmark/agent/` workflow copy:
|
||||
|
||||
- Host surfaces are the runtime surfaces agents actually load.
|
||||
- Duplicating workflow packages under `.truthmark/agent/` would add repository docs with no active host consumer.
|
||||
|
||||
GitHub Copilot prompts, Gemini commands, and top-level managed instruction blocks stay thin:
|
||||
|
||||
- They point to host-native workflow entrypoints when a host skill package exists.
|
||||
- They do not embed full workflow bodies or cross-host invocation lists.
|
||||
|
||||
Generated-surface checks report missing or stale configured host-native skill package files.
|
||||
|
||||
Workflow manifest entries use review-oriented questions that surface as a WorkflowState `reviewChecklist`.
|
||||
|
||||
Evidence-oriented entries surface as `evidencePrompts`.
|
||||
|
||||
Generated GitHub Copilot prompts and Gemini commands act as compact host entrypoint adapters:
|
||||
|
||||
- They direct the current invocation to host-local skill package files.
|
||||
- They avoid dispatching another Truthmark command.
|
||||
- They do not embed duplicate workflow bodies or cross-host invocation lists.
|
||||
|
||||
Truth Sync generated procedures use a product-truth decision before canonical truth writes:
|
||||
|
||||
- Update or route product truth only when a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed.
|
||||
- Internal implementation changes default to engineering truth.
|
||||
|
||||
Truth Sync owns bounded topology repair before normal syncing:
|
||||
|
||||
- Missing, stale, broad, overloaded, or catch-all routing is repaired inside Sync when the repair is safe and in scope.
|
||||
- Safe repair stays limited to affected route/truth owners.
|
||||
- Unsafe, ambiguous, or out-of-scope topology repair is handed off manually to Truth Structure.
|
||||
|
||||
Truth Sync performs decision context capture from the current task conversation:
|
||||
|
||||
- Agents review user-provided decisions, rationale, constraints, tradeoffs, rejection reasons, and scope boundaries.
|
||||
- Agents carry that context into Sync Intent.
|
||||
- Supported context is placed in the correct product or engineering truth lane.
|
||||
- The report records whether context was placed, skipped because none was provided, or handed off for manual review.
|
||||
|
||||
Truth Document procedures tell agents to write diff-friendly truth docs:
|
||||
|
||||
- Prefer one durable claim per bullet or line.
|
||||
- Keep paragraphs to one or two short sentences.
|
||||
- Use bullets or tables for rules, criteria, fields, files, and lists.
|
||||
|
||||
Truth Structure stays topology-first:
|
||||
|
||||
- It creates skeletal starter truth docs only when missing ownership would block future workflows.
|
||||
- Starter docs are ownership anchors, not substantive behavior writeups.
|
||||
- Template-section authoring, doc-shape repair, and architecture-doc prose guidance stay out of the Structure procedure.
|
||||
|
||||
Other write-capable truth workflows preserve lane-specific classification before canonical truth writes.
|
||||
|
||||
Read-only Preview and Check surfaces classify lane ownership for reporting without write-authorizing phrasing.
|
||||
|
||||
The manual Truth Realize prompt path uses Realize-specific lane guidance:
|
||||
|
||||
- Read product truth as requirements.
|
||||
- Read engineering truth as implementation context.
|
||||
- Do not write truth docs or truth routing while realizing docs into code.
|
||||
|
||||
Truth Preview keeps route selection thin:
|
||||
|
||||
- Read the root route index first.
|
||||
- Read only child route files relevant to the selected scope or changed paths.
|
||||
- Report unresolved manual handoff questions rather than final correctness.
|
||||
|
||||
Truth Check and read-only route auditors use route-first bounded inspection for lane and cross-lane relationship checks:
|
||||
|
||||
- Narrow audits stay within the routed area plus directly linked counterpart docs.
|
||||
- Root-wide health first builds a route-map/index from route files.
|
||||
- Missing product links for user-visible engineering docs are second-pass review diagnostics rather than default full-document reads.
|
||||
|
||||
Truth Sync generated procedures and report templates include a transient Sync Intent checkpoint that records:
|
||||
|
||||
- changed code reviewed
|
||||
- affected route/truth owner
|
||||
- target truth docs
|
||||
- intended update
|
||||
- evidence to verify
|
||||
- user-provided decisions/rationale
|
||||
- no-update-needed rationale
|
||||
- blockers
|
||||
|
||||
Optional CLI repository-intelligence helpers are compact advisory cards:
|
||||
|
||||
- `workflow status` reports affected files, likely route owners, suggested truth docs, open questions, skipped helper status, and compact write-boundary suggestions.
|
||||
- `impact` exposes branch-diff routing data.
|
||||
- Neither helper emits source-file or truth-doc body contents.
|
||||
|
||||
Truth Sync workflow status separates impacted primary truth docs from candidate stale truth docs and route files.
|
||||
|
||||
This keeps stale repository-truth correction available without making every indexed doc look like the starting scope.
|
||||
|
||||
## Triggers
|
||||
|
||||
@@ -26,10 +141,37 @@ Workflow manifest entries use review-oriented questions that surface as a Workfl
|
||||
- Explicit host invocations run manual workflows.
|
||||
- Truth Sync is the finish-time workflow when functional code changed.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Source workflow renderers and manifest entries under `src/agents/**` and `src/templates/**`.
|
||||
- `.truthmark/config.yml` platform selections.
|
||||
- Committed host-native workflow files and managed instruction blocks.
|
||||
- Optional workflow-status and impact helper outputs.
|
||||
|
||||
## Execution Model
|
||||
|
||||
Committed workflow files are the runtime contract. The CLI installs and validates surfaces but does not act as daemon, database, or workflow orchestrator.
|
||||
|
||||
## Steps
|
||||
|
||||
- Maintainers edit source renderers, workflow manifest entries, or shared workflow guidance.
|
||||
- `truthmark init` refreshes configured generated surfaces.
|
||||
- Agents load host-native skill packages, prompt adapters, command adapters, or managed instruction blocks.
|
||||
- Agents inspect the checkout directly and use optional helpers only as compact advisory context.
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
- Generated-surface state is represented by committed files.
|
||||
- Stale generated surfaces are reported by check and repaired by rerunning init.
|
||||
- Missing helper output does not block direct-checkout workflow execution.
|
||||
|
||||
## Outputs
|
||||
|
||||
- Host-native skill packages and support files for configured platforms.
|
||||
- Compact prompt and command adapters where applicable.
|
||||
- Managed instruction blocks with non-versioned refresh guidance.
|
||||
- Workflow reports produced by the running agent, not by a Truthmark daemon.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/agent-native-workflow-injection.md`
|
||||
@@ -44,10 +186,24 @@ Committed workflow files are the runtime contract. The CLI installs and validate
|
||||
- Decision (2026-06-16): Truth Sync uses a transient Sync Intent checklist in generated procedures and report templates before truth writes; it is not a persistent plan object or lifecycle artifact.
|
||||
- Decision (2026-06-18): Truth Sync treats user-provided decision rationale from the current task conversation as first-class sync input. The workflow records that context in Sync Intent, routes it to the correct product or engineering truth section when supported, and reports where it was placed, skipped because none was provided, or handed off for manual review.
|
||||
- Decision (2026-06-17): Source manifest/renderers are the workflow-generation authority; configured host skill directories are native generated packages with colocated resources. Truthmark does not emit a separate `.truthmark/agent/` workflow copy when no host surface consumes it.
|
||||
- Decision (2026-06-18): Fresh configs do not assume Codex, OpenCode, or any other host platform. Host-specific surfaces are generated only for explicit `platforms` entries.
|
||||
- Decision (2026-06-18): Generated helper manifest and helper policy files are retired. Validation helpers remain as optional workflow metadata and explicit `truthmark validate ...` commands, not package support files.
|
||||
- Decision (2026-06-18): Truth Preview is read-only and explicit, so it remains a compact Copilot/Gemini prompt-command body instead of a standalone native skill package.
|
||||
- Decision (2026-06-18): Truth Sync retains bounded topology repair. Missing, stale, broad, overloaded, or catch-all route ownership is repaired inside Sync when safe and scoped to the changed functional code; only unsafe, ambiguous, or out-of-scope topology repair is handed off manually to Truth Structure.
|
||||
|
||||
## Rationale
|
||||
|
||||
Committed host-native workflow files keep agent behavior reviewable in Git while avoiding a required live Truthmark runtime.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- The runtime does not orchestrate agents.
|
||||
- The runtime does not create hidden off-repo workflow packets.
|
||||
- The runtime does not make optional helpers mandatory preflight steps.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when workflow manifest fields, generated surface paths, helper metadata, or managed instruction behavior changes.
|
||||
Update this doc when workflow manifest fields, generated surface paths, optional validation metadata, or managed instruction behavior changes.
|
||||
|
||||
## Source References
|
||||
|
||||
@@ -56,6 +212,7 @@ Update this doc when workflow manifest fields, generated surface paths, helper m
|
||||
- ../../../../src/agents/workflow-manifest.ts
|
||||
- ../../../../src/agents/truth-sync.ts
|
||||
- ../../../../src/sync/report.ts
|
||||
- ../../../../src/agents/shared.ts
|
||||
- ../../../../src/templates/workflow-surfaces.ts
|
||||
- ../../../../src/templates/generated-surfaces.ts
|
||||
- ../../../../src/checks/generated-surfaces.ts
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user