mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
chore: prepare Truthmark 2.2.6 (#28)
* feat: add compact truth-doc prose guidance * chore: prepare Truthmark 2.2.6 * fix: preserve truth doc line discipline * docs: emphasize ongoing truth curation * docs(truth): add behavior scenarios to truth docs --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
This commit is contained in:
Merlin's Cat
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
last_reviewed: 2026-06-12
|
||||
last_reviewed: 2026-06-26
|
||||
source_of_truth:
|
||||
- ../../README.md
|
||||
- ../truthmark/product/capabilities/agent-native-workflow-injection.md
|
||||
@@ -33,6 +33,10 @@ Truthmark keeps repository documentation aligned with agent-made code changes so
|
||||
|
||||
Canonical truth documents are human-facing Git-review artifacts. Human maintainers are the primary reviewers; agents write and maintain truth docs, but agents are not the only consumers.
|
||||
|
||||
Truthmark's product value is ongoing truth-doc curation, not one-shot documentation generation.
|
||||
|
||||
Truthmark keeps truth docs bounded, evidence-backed, and reviewable as agents continue changing code.
|
||||
|
||||
Truth-doc structure, wording, and style must be friendly for humans to read and understand.
|
||||
|
||||
Human-friendly truth docs:
|
||||
@@ -86,6 +90,7 @@ Optional integrations are acceptable only when they preserve host-native agent w
|
||||
6. **Human review stays central.** Truthmark produces reviewable documentation changes, not silent approval or merge authority.
|
||||
7. **Local-first simplicity wins.** Add dependencies, services, or runtime layers only when they preserve the no-blockade repository-file workflow.
|
||||
8. **Truth docs stay human-friendly.** Truth docs must be structured and written for maintainers to review, scan, and understand before they are optimized for agent or machine consumption.
|
||||
9. **Curation beats generation.** Truthmark should route overgrown or mixed-owner docs toward Structure instead of rewarding more appended prose.
|
||||
|
||||
## Required Product Boundary Check
|
||||
|
||||
@@ -107,6 +112,8 @@ A plan that cannot answer these questions is not ready for implementation.
|
||||
- Decision (2026-06-12): Repository rules cite this document so agents must check product boundaries before generating new designs or plans.
|
||||
- Decision (2026-06-12): Truthmark workflows must stay 100% operational from repository files and host-native agent surfaces; missing packages, CLIs, daemons, services, or plugins must not block normal workflow execution.
|
||||
- Decision (2026-06-12): Human-facing readability is part of the Truthmark product boundary for canonical truth documents.
|
||||
- Decision (2026-06-26): Ongoing truth-doc curation is a primary product value.
|
||||
- Marketing should emphasize bounded ownership, evidence-backed updates, Git-reviewable docs, and Structure handoff for overgrown docs instead of generic documentation generation.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-20
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Check Diagnostics
|
||||
@@ -49,6 +49,29 @@ It covers route coverage, lane shape, lane drift, traceability, frontmatter, gen
|
||||
- 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.
|
||||
|
||||
## Behavior Scenarios
|
||||
|
||||
#### Scenario: Generated surface drift is review-only
|
||||
|
||||
- **GIVEN** a committed generated workflow surface differs from the current renderer output
|
||||
- **WHEN** `truthmark check` compares rendered surfaces with checked-in files
|
||||
- **THEN** it reports a `generated-surface` review diagnostic for the stale path
|
||||
- **AND** it does not mutate files during the check
|
||||
|
||||
#### Scenario: Route relationship metadata stays in route YAML
|
||||
|
||||
- **GIVEN** a truth document frontmatter block declares `realized_by`, `realizes`, or `depends_on`
|
||||
- **WHEN** `truthmark check` validates frontmatter
|
||||
- **THEN** it reports the relationship metadata as invalid frontmatter
|
||||
- **AND** keeps relationship authority in fenced route YAML entries
|
||||
|
||||
#### Scenario: Duplicate route entries merge compatible relationships
|
||||
|
||||
- **GIVEN** route files contain duplicate entries for the same truth document path, kind, and lane
|
||||
- **WHEN** Check validates route traceability
|
||||
- **THEN** it merges `realized_by`, `realizes`, and `depends_on` metadata by unique sorted set
|
||||
- **AND** conflicting duplicate kinds or lanes remain area-index errors.
|
||||
|
||||
## Flows And States
|
||||
|
||||
- Check loads config and routed truth docs from the active checkout.
|
||||
@@ -91,13 +114,12 @@ Update when check categories, severity rules, lane audit behavior, or product ki
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../../../src/checks/check.ts
|
||||
- ../../../../src/checks/areas.ts
|
||||
- ../../../../src/checks/decisions.ts
|
||||
- ../../../../src/checks/frontmatter.ts
|
||||
- ../../../../tests/checks/frontmatter.test.ts
|
||||
- `src/checks/areas.ts`
|
||||
- `src/checks/decisions.ts`
|
||||
- `src/checks/frontmatter.ts`
|
||||
- `tests/checks/frontmatter.test.ts`
|
||||
- `src/output/diagnostic.ts`
|
||||
- src/checks/check.ts
|
||||
- src/checks/areas.ts
|
||||
- src/checks/decisions.ts
|
||||
- src/checks/frontmatter.ts
|
||||
- src/checks/generated-surfaces.ts
|
||||
- src/output/diagnostic.ts
|
||||
- tests/checks/check.test.ts
|
||||
- tests/checks/frontmatter.test.ts
|
||||
- tests/templates/generated-surfaces.test.ts
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-21
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Init And Scaffold
|
||||
@@ -61,6 +61,13 @@ Those files may contain user-owned instructions alongside old Truthmark injectio
|
||||
|
||||
Generated truth-doc templates keep kind-specific and section-specific authoring comments in the template files.
|
||||
|
||||
Engineering behavior templates include a `Behavior Scenarios` section after `Core Rules`:
|
||||
|
||||
- Scenario blocks are optional and clarify normal, fallback, or compatibility-critical behavior.
|
||||
- Scenario bullets use `GIVEN`, `WHEN`, `THEN`, and optional `AND` labels.
|
||||
- Scenario guidance frames entries as current implemented truth rather than future requirements.
|
||||
- Scenario bullets do not replace source-backed behavior claims or Source References.
|
||||
|
||||
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.
|
||||
@@ -92,9 +99,33 @@ Capability docs own:
|
||||
|
||||
- Scaffolded paths derive from `truthmark.workspace`.
|
||||
- Template filenames match `truth_kind` values.
|
||||
- Engineering behavior templates provide optional current-state scenario blocks for normal, fallback, or compatibility-critical behavior.
|
||||
- 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.
|
||||
|
||||
## Behavior Scenarios
|
||||
|
||||
#### Scenario: Fresh config does not assume a host platform
|
||||
|
||||
- **GIVEN** a repository uses the default generated Truthmark config
|
||||
- **WHEN** `truthmark init` creates or refreshes the scaffold
|
||||
- **THEN** `platforms` remains omitted by default
|
||||
- **AND** host-specific workflow surfaces require explicit platform configuration
|
||||
|
||||
#### Scenario: Retired Gemini surfaces are preserved for manual cleanup
|
||||
|
||||
- **GIVEN** a repository contains retired Gemini instruction or command surfaces
|
||||
- **WHEN** `truthmark init` removes auto-removable retired generated artifacts
|
||||
- **THEN** it leaves `GEMINI.md` and `.gemini/**` in place
|
||||
- **AND** check diagnostics tell maintainers to review stale Gemini guidance manually
|
||||
|
||||
#### Scenario: Engineering behavior templates support compact scenarios
|
||||
|
||||
- **GIVEN** Truthmark renders the editable `engineering-behavior.md` template
|
||||
- **WHEN** maintainers create or refresh truth-doc templates
|
||||
- **THEN** the template includes an optional `Behavior Scenarios` section after `Core Rules`
|
||||
- **AND** the guidance frames scenarios as current implemented truth rather than `SHALL`-style future requirements
|
||||
|
||||
## Flows And States
|
||||
|
||||
- `truthmark init` creates or refreshes workspace scaffold files.
|
||||
@@ -121,11 +152,16 @@ Capability docs own:
|
||||
- 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.
|
||||
- Decision (2026-06-21): Init does not delete retired Gemini surfaces automatically; users remove stale injected Gemini guidance manually after reviewing `GEMINI.md` and `.gemini/**`.
|
||||
- Decision (2026-06-26): Engineering behavior templates may use compact scenario blocks for behavior clarity.
|
||||
- Scenario guidance adopts the useful requirement/scenario shape from specification formats while preserving Truthmark's current-state, evidence-backed truth-doc role.
|
||||
- The template avoids `SHALL`-style future requirements and does not require a scenario for every rule.
|
||||
|
||||
## Rationale
|
||||
|
||||
Fixed workspace-derived scaffold paths keep Truthmark predictable while route files provide the semantic ownership layer.
|
||||
|
||||
Optional scenario blocks make normal and fallback behavior easier to review in Git without turning truth docs into future-looking requirement specs.
|
||||
|
||||
Keeping templates kind-specific and moving global prose style into workflow guidance reduces generated-template bloat.
|
||||
|
||||
## Non-Goals
|
||||
@@ -145,3 +181,4 @@ 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/init/truth-doc-templates.test.ts
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: active
|
||||
last_reviewed: 2026-06-14
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Repository Truth Docs
|
||||
@@ -11,8 +11,12 @@ README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf
|
||||
|
||||
Current leaf docs:
|
||||
|
||||
- [Overview](overview.md)
|
||||
- [Repository Bootstrap Routing](bootstrap-routing.md) — provisional broad-route handoff for fresh or under-structured repositories.
|
||||
- [Repository Intelligence](repository-intelligence.md) — RepoIndex, RouteMap, ImpactSet, evidence, freshness, and WorkflowState behavior.
|
||||
- [Repository Overview](overview.md) — guardrail that prevents broad repository overviews from becoming catch-all implementation truth.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../routes/areas/repository.md
|
||||
- docs/truthmark/engineering/repository/bootstrap-routing.md
|
||||
- docs/truthmark/engineering/repository/repository-intelligence.md
|
||||
- docs/truthmark/engineering/repository/overview.md
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-17
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Repository Bootstrap Routing
|
||||
@@ -81,5 +81,6 @@ Keep this doc short. When a repository has real bounded routes, prefer updating
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../routes/areas/repository.md
|
||||
- ../../../../.truthmark/config.yml
|
||||
- docs/truthmark/engineering/behaviors/init-and-scaffold.md
|
||||
- src/templates/init-files.ts
|
||||
- .truthmark/config.yml
|
||||
|
||||
@@ -1,111 +1,90 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-20
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Repository Overview
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the user/system outcome this behavior protects and why it exists.
|
||||
Include the problem boundary and durable value; exclude roadmap, implementation plan, and historical narrative.
|
||||
List the code, config, docs, or tests that support the claim in Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
Describe why the default repository behavior surface exists and what outcome it protects.
|
||||
This doc records the repository-directory guardrail that broad repository docs are indexes or handoffs, not catch-all implementation truth.
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent behavior surface this document owns.
|
||||
Include in-scope actors, entrypoints, state/data owned by this doc, and explicit handoffs to neighboring truth docs.
|
||||
Split into another leaf doc when content introduces a distinct outcome, state machine, rule family, external contract, or route owner.
|
||||
Keep README.md files as indexes only.
|
||||
-->
|
||||
It covers the repository truth-doc directory shape and the handoff away from legacy broad overview ownership.
|
||||
|
||||
This bounded leaf truth doc owns the default repository behavior surface created by Truthmark.
|
||||
|
||||
This doc was created from the editable engineering-behavior template at docs/truthmark/templates/engineering-behavior.md.
|
||||
It does not own implementation behavior under `src/**`, route-map behavior, or repository-intelligence output details.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
<!--
|
||||
Describe only current implemented behavior in present tense.
|
||||
Cover observable behavior, important defaults, and user/system-visible effects; exclude desired future behavior and speculative design.
|
||||
Every non-obvious claim should be checkable from Source References.
|
||||
-->
|
||||
|
||||
- Document current behavior here when implementation changes make repository truth incomplete.
|
||||
- Truthmark no longer treats this file as the default behavior owner for broad repository code surfaces.
|
||||
- Init uses `engineering/repository/bootstrap-routing.md` as the provisional broad-route handoff when a fresh repository needs initial routeability.
|
||||
- Normal behavior truth belongs in bounded route-owned leaf docs after Truth Structure identifies the durable owner.
|
||||
- Repository-intelligence behavior lives in `engineering/repository/repository-intelligence.md`.
|
||||
- README files in truth-doc directories remain indexes instead of Truth Sync targets.
|
||||
|
||||
## Core Rules
|
||||
|
||||
<!--
|
||||
Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints.
|
||||
Separate rules from incidental implementation details; cite current implementation or tests for rule enforcement.
|
||||
-->
|
||||
- Do not append unrelated implementation behavior to this overview.
|
||||
- Use `bootstrap-routing.md` when the repository still needs a provisional broad-route handoff.
|
||||
- Use bounded route-owned truth docs for real implementation behavior.
|
||||
- Use `repository-intelligence.md` for RepoIndex, RouteMap, ImpactSet, evidence, freshness, and WorkflowState behavior.
|
||||
|
||||
- Truth README files are indexes; behavior truth belongs in bounded leaf docs.
|
||||
## Behavior Scenarios
|
||||
|
||||
#### Scenario: Broad default routing does not expand the overview
|
||||
|
||||
- **GIVEN** a real code change maps only to a provisional broad repository route
|
||||
- **WHEN** Truth Sync cannot identify a bounded truth owner safely
|
||||
- **THEN** agents run or recommend Truth Structure before updating behavior truth
|
||||
- **AND** they do not append implementation claims to this overview
|
||||
|
||||
#### Scenario: Repository truth docs stay indexable by bounded owner
|
||||
|
||||
- **GIVEN** a maintainer opens the repository truth-doc directory
|
||||
- **WHEN** they choose a target truth doc for repository behavior
|
||||
- **THEN** the directory index points to bounded leaf docs and bootstrap handoffs
|
||||
- **AND** this overview remains a guardrail against catch-all behavior prose
|
||||
|
||||
## Flows And States
|
||||
|
||||
<!--
|
||||
Document state transitions, lifecycle stages, retries, fallbacks, route switches, and important error paths.
|
||||
State 'None beyond current behavior.' when this behavior has no distinct flow or state model.
|
||||
-->
|
||||
|
||||
- None beyond current behavior.
|
||||
- None beyond the broad-overview-to-bounded-owner handoff described above.
|
||||
|
||||
## Contracts
|
||||
|
||||
<!--
|
||||
Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs.
|
||||
Avoid duplicating a separate canonical contract doc; link to it when contract ownership lives elsewhere.
|
||||
-->
|
||||
|
||||
- External contracts should link to the nearest canonical contract doc when one exists.
|
||||
- Route metadata and check diagnostics are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.
|
||||
- Repository-intelligence JSON contracts are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- None.
|
||||
- None. This is an internal engineering guardrail.
|
||||
|
||||
## 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 (2026-06-14): Truth README files are indexes; behavior truth belongs in bounded leaf docs.
|
||||
- Decision (2026-06-26): The repository overview is a guardrail against catch-all truth ownership, not the default behavior owner.
|
||||
- Init creates `bootstrap-routing.md` for provisional broad routes.
|
||||
- Truth Structure creates or repairs bounded owners before normal Truth Sync writes behavior details.
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior and active decisions are this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed behavior; do not use this as a changelog.
|
||||
-->
|
||||
Broad overview docs tend to accumulate unrelated behavior and become hard to review in Git.
|
||||
|
||||
Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals.
|
||||
Keeping this file as a narrow guardrail preserves the old path's intent while directing real behavior to bounded owners.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior this doc intentionally does not own, especially tempting future expansions or neighboring route owners.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
- This doc is not a catch-all for unrelated repository behavior.
|
||||
- This doc is not a catch-all for repository behavior.
|
||||
- This doc is not a route-map, impact, or workflow-state behavior owner.
|
||||
- This doc is not a product capability or external contract.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
- Update this doc when routed implementation changes alter current behavior, rules, contracts, or decisions.
|
||||
Update this doc only when repository-directory ownership, bootstrap handoff behavior, or broad-overview retirement behavior changes.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../routes/areas/repository.md
|
||||
- docs/truthmark/engineering/repository/bootstrap-routing.md
|
||||
- docs/truthmark/engineering/repository/repository-intelligence.md
|
||||
- docs/truthmark/engineering/behaviors/init-and-scaffold.md
|
||||
- docs/truthmark/engineering/repository/README.md
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-21
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Repository Intelligence
|
||||
@@ -69,6 +69,29 @@ It covers RepoIndex, RouteMap, ImpactSet, evidence validation, freshness, and Wo
|
||||
- WorkflowState and ImpactSet expose paths, metadata, diagnostics, and checklists without embedding source-file or truth-doc bodies.
|
||||
- Route relationships remain route-local metadata.
|
||||
|
||||
## Behavior Scenarios
|
||||
|
||||
#### Scenario: Impact maps branch changes to review focus
|
||||
|
||||
- **GIVEN** a branch changes source, test, route, or truth-document paths
|
||||
- **WHEN** Truthmark builds an ImpactSet for the branch
|
||||
- **THEN** it reports affected routes, affected truth docs, affected tests, and unmapped functional-code diagnostics
|
||||
- **AND** it does not infer TypeScript public-symbol changes through language import parsing
|
||||
|
||||
#### Scenario: Workflow status keeps stale candidates signal-based
|
||||
|
||||
- **GIVEN** a changed file maps to primary truth docs and no concrete stale-truth signal names another doc
|
||||
- **WHEN** Sync action context is built
|
||||
- **THEN** `candidateStaleTruthDocs` remains empty
|
||||
- **AND** agents may still inspect another document only when direct checkout evidence reveals a stale claim
|
||||
|
||||
#### Scenario: Evidence validation stays repository-contained
|
||||
|
||||
- **GIVEN** truth evidence names a repository path, glob, line span, or `sha256:` hash
|
||||
- **WHEN** Truthmark validates evidence
|
||||
- **THEN** it checks repository containment and referenced file or glob existence
|
||||
- **AND** it treats optional `symbol` metadata as non-normative metadata rather than TypeScript-specific proof
|
||||
|
||||
## Flows And States
|
||||
|
||||
- RepoIndex and RouteMap are built from committed repository files.
|
||||
@@ -119,21 +142,17 @@ Update when index, route-map, impact, evidence, freshness, or workflow-state out
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../../../src/repo-index/build.ts
|
||||
- ../../../../src/repo-index/file-tree.ts
|
||||
- ../../../../src/repo-index/route-map.ts
|
||||
- ../../../../src/repo-index/types.ts
|
||||
- ../../../../src/impact/build.ts
|
||||
- ../../../../src/impact/types.ts
|
||||
- ../../../../src/evidence/validate.ts
|
||||
- ../../../../src/workflow-state/action-context.ts
|
||||
- ../../../../src/workflow-state/build.ts
|
||||
- ../../../../src/workflow-state/types.ts
|
||||
- ../../../../src/checks/generated-surfaces.ts
|
||||
- ../../../../tests/workflow-state/build.test.ts
|
||||
- `src/repo-index/build.ts`
|
||||
- `src/repo-index/file-tree.ts`
|
||||
- `src/repo-index/route-map.ts`
|
||||
- `src/repo-index/types.ts`
|
||||
- `src/impact/build.ts`
|
||||
- `src/workflow-state/build.ts`
|
||||
- src/repo-index/build.ts
|
||||
- src/repo-index/file-tree.ts
|
||||
- src/repo-index/route-map.ts
|
||||
- src/repo-index/types.ts
|
||||
- src/impact/build.ts
|
||||
- src/impact/types.ts
|
||||
- src/evidence/validate.ts
|
||||
- src/workflow-state/action-context.ts
|
||||
- src/workflow-state/build.ts
|
||||
- src/workflow-state/types.ts
|
||||
- src/checks/generated-surfaces.ts
|
||||
- tests/impact/build.test.ts
|
||||
- tests/evidence/validate.test.ts
|
||||
- tests/workflow-state/build.test.ts
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-21
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Installed Workflow Runtime
|
||||
@@ -92,11 +92,13 @@ Truth Sync performs decision context capture from the current task conversation:
|
||||
- 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:
|
||||
Truth Document and Truth Sync procedures tell agents to write professional, readable truth docs without importing a full external writing prompt:
|
||||
|
||||
- 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.
|
||||
- Prefer specific current-state claims over promotional, symbolic, or generic significance language.
|
||||
- Avoid common AI-writing tells such as vague expert attribution, generic upbeat conclusions, and stock words like "pivotal", "crucial", "underscores", "serves as", "stands as", "showcases", and "landscape".
|
||||
- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
|
||||
- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
|
||||
- Rewrite dense or formulaic prose only when readability improves without removing scope, evidence, decisions, or source references.
|
||||
|
||||
Truth Structure stays topology-first:
|
||||
|
||||
@@ -221,6 +223,8 @@ Committed workflow files are the runtime contract. The CLI installs and validate
|
||||
- Bootstrap-only mappings are blocked topology handoffs until Truth Structure assigns a bounded owner.
|
||||
- Decision (2026-06-21): Cursor workflow generation uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not dynamic `.cursor/rules` files.
|
||||
- Agent Skills are the single current native Cursor workflow representation because they provide description-based selection plus package-local resources.
|
||||
- Decision (2026-06-26): Truth-doc prose guidance uses a compact professional checklist instead of vendoring a full humanizer prompt into generated workflows.
|
||||
- Truthmark keeps the benefit of avoiding AI-style padding while controlling token cost and preserving evidence-backed documentation tone.
|
||||
|
||||
## Rationale
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: product-capability
|
||||
last_reviewed: 2026-06-20
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Agent-Native Workflow Injection
|
||||
@@ -16,6 +16,10 @@ last_reviewed: 2026-06-20
|
||||
|
||||
Repository maintainers and agents can follow the checked-in workflow contract without relying on a live Truthmark daemon, hidden runtime state, or off-repo packet.
|
||||
|
||||
Truthmark turns AI documentation from one-shot generation into ongoing truth-doc curation.
|
||||
|
||||
Maintainers get bounded, evidence-backed, Git-reviewable truth docs that stay connected to code changes.
|
||||
|
||||
## Capability Scope
|
||||
|
||||
This capability covers:
|
||||
@@ -55,6 +59,7 @@ This capability covers:
|
||||
- Truth Sync status separates impacted `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles`.
|
||||
- Agents start with affected route owners.
|
||||
- Evidence-backed stale repository-truth correction remains available beyond the initially affected route set.
|
||||
- Broad, catch-all, mixed-owner, or overgrown truth docs are treated as curation problems that require Structure instead of more appended prose.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
@@ -70,6 +75,8 @@ This capability covers:
|
||||
- Truth Sync routes supported context to the correct truth lane.
|
||||
- Truth Sync reports placement, skip, or manual handoff.
|
||||
- Workflows that create, structure, or audit truth docs still preserve product and engineering truth as separate lanes.
|
||||
- Truth Document and Truth Sync carry compact professional prose guidance for truth-doc edits without embedding a full external humanizer prompt in generated workflow surfaces.
|
||||
- Truthmark positions ongoing truth-doc curation as a core product value rather than presenting itself as a one-shot documentation generator.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
@@ -96,6 +103,10 @@ This capability covers:
|
||||
- Safe repairs happen inside Sync before normal truth syncing; manual Truth Structure handoff is only for unsafe, ambiguous, or out-of-scope topology changes.
|
||||
- Decision (2026-06-21): Cursor uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not dynamic `.cursor/rules` files.
|
||||
- Cursor Agent Skills are the single current native Cursor workflow representation for Truthmark because they support description-based selection plus package-local support resources.
|
||||
- Decision (2026-06-26): Humanizer-style cleanup is adapted only as a compact professional prose checklist.
|
||||
- The workflow must avoid token-heavy prompt imports and must not push truth docs toward personal, rhetorical, or marketing tone.
|
||||
- Decision (2026-06-26): Ongoing truth-doc curation is a primary product value.
|
||||
- Marketing should emphasize bounded ownership, evidence-backed updates, Git-reviewable docs, and Structure handoff for overgrown docs rather than claiming generic documentation generation.
|
||||
|
||||
## Engineering Realization Links
|
||||
|
||||
|
||||
@@ -48,6 +48,16 @@ Separate rules from incidental implementation details; cite current implementati
|
||||
|
||||
{{core_rules}}
|
||||
|
||||
## Behavior Scenarios
|
||||
|
||||
<!--
|
||||
Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.
|
||||
Write scenarios as current truth, not desired requirements: `#### Scenario: <implemented case>` followed by `- **GIVEN** ...`, `- **WHEN** ...`, `- **THEN** ...`, and optional `- **AND** ...` bullets.
|
||||
Keep each bullet evidence-backed and observable; do not force a scenario for every rule.
|
||||
-->
|
||||
|
||||
{{behavior_scenarios}}
|
||||
|
||||
## Flows And States
|
||||
|
||||
<!--
|
||||
|
||||
Reference in New Issue
Block a user