mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
1.2.4 strengthen truth workflow ownership and evidence gates (#3)
* refactor(truthmark): parameterize truth agent paths with routing config * 1.2.4 truth flow research * Context and workflow optimization
This commit is contained in:
MerlinH
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available.
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.3
|
||||
truthmark-version: 1.2.4
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
@@ -20,21 +20,25 @@ Implementation code and canonical truth docs are inspected evidence for current
|
||||
- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/
|
||||
- check that current docs describe current code rather than historical plans
|
||||
- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs
|
||||
- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
|
||||
- check that canonical behavior docs keep active Product Decisions and Rationale sections
|
||||
- optionally run truthmark check when local tooling is available
|
||||
- must not require the truthmark binary; direct inspection is always valid
|
||||
- report issues and suggested fixes without silently rewriting unrelated files
|
||||
- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing
|
||||
Evidence Gate:
|
||||
- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
|
||||
- canonical docs are context, not sole proof when implementation conflicts
|
||||
- remove unsupported findings or mark open questions; validate changed claims if you edit docs
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth docs: docs/truth/**/*.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.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
@@ -50,6 +54,12 @@ Issues found:
|
||||
Fixes suggested:
|
||||
- none
|
||||
|
||||
Evidence checked:
|
||||
- Finding: The root route index is present and maps repository truth owners.
|
||||
Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1
|
||||
Suggested fix: none
|
||||
Confidence: high
|
||||
|
||||
Validation:
|
||||
- truthmark check
|
||||
```
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: truthmark-document
|
||||
description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code.
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.3
|
||||
truthmark-version: 1.2.4
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
@@ -24,43 +24,74 @@ Implementation code and canonical truth docs are inspected evidence for current
|
||||
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- keep feature README.md files as indexes rather than truth-document targets
|
||||
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
|
||||
- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
|
||||
- preserve unrelated authored content
|
||||
When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
|
||||
When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
|
||||
If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
|
||||
Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
|
||||
Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
|
||||
Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
|
||||
Truth-doc ownership gate:
|
||||
- before editing or relying on the implemented behavior and candidate 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 the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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, block with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Evidence Gate:
|
||||
- route-first: map the documented behavior to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, Product 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 block unsupported claims
|
||||
- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
Truth-doc shape repair gate:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership gate 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 block unsupported or stale claims
|
||||
- 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.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth docs: docs/truth/**/*.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.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Document: completed
|
||||
|
||||
Implementation reviewed:
|
||||
- src/api/orders/**
|
||||
- src/routing/area-resolver.ts
|
||||
|
||||
Truth docs created:
|
||||
- docs/features/orders/order-submission.md
|
||||
- docs/truth/contracts.md
|
||||
|
||||
Truth docs updated:
|
||||
- docs/features/contracts.md
|
||||
- docs/truth/check-diagnostics.md
|
||||
|
||||
Truth docs restructured:
|
||||
- docs/truth/check-diagnostics.md
|
||||
|
||||
Routing updated:
|
||||
- docs/truthmark/areas/orders.md
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Route resolution behavior is documented in the contracts truth doc.
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Documented existing order submission behavior from route handlers and tests.
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification.
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.3
|
||||
truthmark-version: 1.2.4
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
@@ -21,13 +21,23 @@ Truth Realize is doc-first:
|
||||
Workflow:
|
||||
|
||||
1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md.
|
||||
2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code.
|
||||
2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code.
|
||||
3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
4. Update functional code only so implementation matches the truth docs.
|
||||
Truth-doc ownership gate:
|
||||
- before editing or relying on source truth docs before writing code, 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 source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, block before writing code and recommend Truth Structure or Truth Document
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
|
||||
5. Do not edit truth docs or truth routing while realizing those docs.
|
||||
6. Run relevant tests for the changed code.
|
||||
7. Report changed code files and verification steps.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
|
||||
Read and write boundaries:
|
||||
|
||||
@@ -41,7 +51,7 @@ Report completion in this shape:
|
||||
Truth Realize: completed
|
||||
|
||||
Truth docs used:
|
||||
- docs/features/authentication.md
|
||||
- docs/truth/authentication/session-timeout.md
|
||||
|
||||
Code updated:
|
||||
- src/auth/session.ts
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: truthmark-structure
|
||||
description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs.
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, or needs split/repair. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.3
|
||||
truthmark-version: 1.2.4
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
@@ -18,44 +18,68 @@ Implementation code and canonical truth docs are inspected evidence for current
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
|
||||
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
|
||||
When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
|
||||
When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
|
||||
If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
|
||||
Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
|
||||
- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
|
||||
- preserve unrelated authored content
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root.
|
||||
Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root.
|
||||
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 feature docs.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
Truth-doc ownership gate:
|
||||
- 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 block with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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, block with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and 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
|
||||
- one truth doc owns unrelated behaviors or unrelated endpoint families
|
||||
- the configured feature root has many direct non-index docs
|
||||
- the configured truth root has many direct non-index docs
|
||||
- a changed controller, route, or service cannot map to a specific behavior doc
|
||||
- Truth Sync would need to create a new generic feature doc because routing is too broad
|
||||
- Truth Sync would need to create a new generic truth doc because routing is too broad
|
||||
- endpoint or controller names reveal domains missing from docs/truthmark/areas/**
|
||||
Use these review thresholds as guidance:
|
||||
- more than 10 direct feature docs in one folder
|
||||
- more than 10 direct truth docs in one folder
|
||||
- more than 15 leaf areas in one child route file
|
||||
- more than 8 truth docs mapped to one area
|
||||
- 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
|
||||
- create route files under docs/truthmark/areas/ when a product/domain boundary is clear
|
||||
- create feature docs under the configured feature root only when behavior lacks a current doc
|
||||
- create behavior truth docs under the configured truth root only when behavior lacks a current doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded leaf truth docs at <feature-root>/<domain>/<behavior>.md
|
||||
- keep feature docs behavior-oriented, not endpoint-oriented
|
||||
- prefer bounded leaf truth docs at <truth-root>/<domain>/<behavior>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc exists
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
|
||||
Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair gate:
|
||||
- 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 gate 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 block unsupported or stale claims
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Evidence Gate:
|
||||
- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product 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 block unsupported claims
|
||||
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 routed canonical current-truth docs missing Product Decisions or Rationale sections.
|
||||
- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
|
||||
Portable fallback:
|
||||
@@ -67,25 +91,31 @@ Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth docs: docs/truth/**/*.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.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Structure: completed
|
||||
Topology reviewed:
|
||||
- controllers: src/auth/**
|
||||
- docs root: docs/features
|
||||
- docs root: docs/truth
|
||||
- route files: docs/truthmark/areas.md
|
||||
Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
Truth docs created:
|
||||
- docs/features/authentication.md
|
||||
- docs/truth/authentication/session.md
|
||||
Truth docs split:
|
||||
- docs/truth/authentication/README.md -> docs/truth/authentication/session.md
|
||||
Truth docs restructured:
|
||||
- docs/truth/authentication/README.md
|
||||
Evidence checked:
|
||||
- Claim: Session behavior belongs to a dedicated Authentication truth owner.
|
||||
Evidence: src/auth/** / docs/truthmark/areas.md:7
|
||||
Result: supported
|
||||
Topology decisions:
|
||||
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
|
||||
Notes:
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: truthmark-sync
|
||||
description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes.
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.3
|
||||
truthmark-version: 1.2.4
|
||||
---
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
@@ -20,20 +20,45 @@ Implementation code and canonical truth docs are inspected evidence for current
|
||||
6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
|
||||
Topology quality gate:
|
||||
- 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 feature doc
|
||||
- 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
|
||||
- block 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
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a feature README
|
||||
- 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
|
||||
When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
|
||||
When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
|
||||
If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
|
||||
Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
|
||||
Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
|
||||
Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
|
||||
Truth-doc ownership gate:
|
||||
- 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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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, block with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and 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 `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
Truth-doc shape repair gate:
|
||||
- Truth Sync may restructure only truth docs impacted by the current functional-code change.
|
||||
- repair shape in place only after the ownership gate 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
- 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, Product 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 block unsupported claims
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
@@ -43,12 +68,10 @@ Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth docs: docs/truth/**/*.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.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
### Truth Sync Worker
|
||||
The parent provides the task focus and any repository context already gathered.
|
||||
Worker rules:
|
||||
@@ -60,8 +83,12 @@ Worker rules:
|
||||
Return result in this shape:
|
||||
- status: completed | blocked
|
||||
- changedCodeReviewed: string[]
|
||||
- ownershipReviewed: string[]
|
||||
- structureRequired?: string[]
|
||||
- truthDocsUpdated: string[]
|
||||
- routingDocsUpdated: string[]
|
||||
- truthDocsSplit?: string[]
|
||||
- evidenceChecked: { claim: string; evidence: string[]; result: supported | narrowed | removed | blocked }[]
|
||||
- notes: string[]
|
||||
- blockedReason?: string
|
||||
- manualReviewFiles?: string[]
|
||||
@@ -70,7 +97,9 @@ Parent post-sync verification:
|
||||
- block on any unrelated diff caused by the sync step
|
||||
- block if functional code changed during sync
|
||||
- verify the worker report matches the required headings and sections
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, Evidence, and Result entries under Evidence checked
|
||||
- verify the updated docs correspond to the reviewed changed-code surface
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired
|
||||
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -80,7 +109,12 @@ Changed code reviewed:
|
||||
- src/auth/session.ts
|
||||
|
||||
Truth docs updated:
|
||||
- docs/features/repository/overview.md
|
||||
- docs/truth/repository/overview.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
|
||||
Reference in New Issue
Block a user