diff --git a/.antigravity/rules/truthmark-check.md b/.antigravity/rules/truthmark-check.md new file mode 100644 index 0000000..54881e7 --- /dev/null +++ b/.antigravity/rules/truthmark-check.md @@ -0,0 +1,92 @@ +# Truthmark Check + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Antigravity entrypoint for Truthmark Check. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-check + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +# Truthmark Check + +Use this skill to audit repository truth health. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- 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 +- 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. +- check that current docs describe current code rather than historical plans +- keep lane and cross-lane checks route-first and bounded: + - for a narrow audit, inspect only the routed area and directly linked counterpart docs + - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves + - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage +- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering +- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility +- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors +- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics +- check engineering docs do not contain product promises, product rationale, or Product Decisions sections +- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable +- check that route files map code surfaces to canonical truth docs when route files exist +- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure +- check that canonical docs keep lane-appropriate 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 checklist: +- 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 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. + +## Report Template + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/routes/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Evidence checked: +- Finding: The root route index is present and maps repository truth owners. + Evidence: docs/truthmark/routes/areas.md:1 + Suggested fix: none + Confidence: high + +Validation: +- truthmark check +``` diff --git a/.antigravity/rules/truthmark-document.md b/.antigravity/rules/truthmark-document.md new file mode 100644 index 0000000..6f58103 --- /dev/null +++ b/.antigravity/rules/truthmark-document.md @@ -0,0 +1,132 @@ +# Truthmark Document + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Antigravity entrypoint for Truthmark Document. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-document + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- 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: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document + - 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. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- stop 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 +- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value +- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests +- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter +- keep engineering behavior truth 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 +Truth-doc ownership review: +- 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 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 +Evidence checklist: +- 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, 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 truth doc changed, report why current truth was already sufficient or why documentation was blocked +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. +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. +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 +- 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. +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. +Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report --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 +- 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 +- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable + +## Report Template + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/routing/area-resolver.ts + +Ownership reviewed: +- docs/truthmark/routes/areas.md + +Truth docs created: +- docs/truthmark/engineering/contracts/routing.md + +Truth docs updated: +- docs/truthmark/engineering/behaviors/check-diagnostics.md + +Truth docs restructured: +- docs/truthmark/engineering/behaviors/check-diagnostics.md + +Routing updated: +- docs/truthmark/routes/areas.md + +Evidence checked: +- Claim: Route resolution behavior is documented in the contracts truth doc. + Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9 + Result: supported + +Notes: +- Documented routing and behavior from route handlers and tests. +``` diff --git a/.antigravity/rules/truthmark-realize.md b/.antigravity/rules/truthmark-realize.md new file mode 100644 index 0000000..59f99d7 --- /dev/null +++ b/.antigravity/rules/truthmark-realize.md @@ -0,0 +1,71 @@ +# Truthmark Realize + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Antigravity entrypoint for Truthmark Realize. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-realize + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then read tests and the relevant functional code. +3. 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. +Truth-doc ownership review: +- 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, stop before writing code and recommend Truth Structure or Truth Document +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff 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 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 + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs + +## Report Template + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` diff --git a/.antigravity/rules/truthmark-structure.md b/.antigravity/rules/truthmark-structure.md new file mode 100644 index 0000000..0cc5249 --- /dev/null +++ b/.antigravity/rules/truthmark-structure.md @@ -0,0 +1,150 @@ +# Truthmark Structure + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Antigravity entrypoint for Truthmark Structure. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-structure + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +Description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. + +## Procedure + +Use this skill to design or repair Truthmark area structure. + +Truth Structure is agent-native: +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- 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: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document + - 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. +- 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 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 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. + +- 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 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. +Do: +- inspect the named code area +- infer bounded product or behavior ownership +- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review +- create or update the child route entry or file +- create starter truth docs only where current truth is missing +- report the initial truth boundary +Do not: +- do not edit functional code +- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it +- do not patch broad or mixed-owner docs in place +- do not create generic catch-all docs +- do not treat README files as Sync targets +## 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 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 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 +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 +- either configured lane 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 truth doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/** +Use these review thresholds as guidance: +- 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 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 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//.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 +- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +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 +- 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, 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. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +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. + +## Report Template + +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- product docs root: docs/truthmark/product +- engineering docs root: docs/truthmark/engineering +- route files: docs/truthmark/routes/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/routes/areas.md +Initial truth boundary: +- Area: Authentication +- Code: src/auth/** +- Product owner: docs/truthmark/product/capabilities/authentication-session.md +- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md +- Scope: session behavior only +Truth docs created: +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md +Truth docs split: +- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md +Truth docs restructured: +- docs/truthmark/truth/authentication/README.md +Evidence checked: +- Claim: Session behavior belongs to a dedicated Authentication truth owner. + Evidence: src/auth/** / docs/truthmark/routes/areas.md:7 + Result: supported +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.antigravity/rules/truthmark-sync.md b/.antigravity/rules/truthmark-sync.md new file mode 100644 index 0000000..6ac4501 --- /dev/null +++ b/.antigravity/rules/truthmark-sync.md @@ -0,0 +1,126 @@ +# Truthmark Sync + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Antigravity entrypoint for Truthmark Sync. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-sync + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +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. +Explicit invocation runs immediately when the user directly requests this workflow. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. 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. +5. Product truth decision: + - ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed + - if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering + - if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes + - when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes + - when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document +6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff. +7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence. +8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +9. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +10. Fill Sync Intent before editing truth docs or truth routing files: + - Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected + - Affected route/truth owner: bounded route area or canonical truth owner that maps the change + - Target truth docs: docs expected to change, or docs reviewed and left unchanged + - Intended update: claim/doc/routing update planned before writing + - Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff + - 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, 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, 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 +- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes +Optional validation tooling: +- you may run truthmark check when local tooling is available +- you may validate the final report with `truthmark validate sync-report --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 +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 +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 +- 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 +- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files + +## Report Template + +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Sync Intent: +- Changed code reviewed: src/auth/session.ts +- Affected route/truth owner: docs/truthmark/routes/areas.md +- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md +- Intended update: Update session timeout behavior. +- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 +- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency +- No-update-needed rationale: not applicable; mapped truth is stale +- Blockers: none + +Ownership reviewed: +- docs/truthmark/routes/areas.md + +Truth docs updated: +- docs/truthmark/engineering/repository/bootstrap-routing.md + +Decision/rationale captured: +- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale. + +Evidence checked: +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 + Result: supported + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/routes/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.cursor/rules/truthmark-check.mdc b/.cursor/rules/truthmark-check.mdc new file mode 100644 index 0000000..fdfaf96 --- /dev/null +++ b/.cursor/rules/truthmark-check.mdc @@ -0,0 +1,97 @@ +--- +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. +alwaysApply: false +--- + +# Truthmark Check + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Cursor entrypoint for Truthmark Check. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-check + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +# Truthmark Check + +Use this skill to audit repository truth health. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- 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 +- 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. +- check that current docs describe current code rather than historical plans +- keep lane and cross-lane checks route-first and bounded: + - for a narrow audit, inspect only the routed area and directly linked counterpart docs + - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves + - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage +- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering +- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility +- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors +- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics +- check engineering docs do not contain product promises, product rationale, or Product Decisions sections +- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable +- check that route files map code surfaces to canonical truth docs when route files exist +- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure +- check that canonical docs keep lane-appropriate 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 checklist: +- 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 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. + +## Report Template + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/routes/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Evidence checked: +- Finding: The root route index is present and maps repository truth owners. + Evidence: docs/truthmark/routes/areas.md:1 + Suggested fix: none + Confidence: high + +Validation: +- truthmark check +``` diff --git a/.cursor/rules/truthmark-document.mdc b/.cursor/rules/truthmark-document.mdc new file mode 100644 index 0000000..d64ca3b --- /dev/null +++ b/.cursor/rules/truthmark-document.mdc @@ -0,0 +1,137 @@ +--- +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. +alwaysApply: false +--- + +# Truthmark Document + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Cursor entrypoint for Truthmark Document. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-document + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- 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: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document + - 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. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- stop 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 +- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value +- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests +- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter +- keep engineering behavior truth 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 +Truth-doc ownership review: +- 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 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 +Evidence checklist: +- 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, 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 truth doc changed, report why current truth was already sufficient or why documentation was blocked +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. +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. +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 +- 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. +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. +Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report --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 +- 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 +- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable + +## Report Template + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/routing/area-resolver.ts + +Ownership reviewed: +- docs/truthmark/routes/areas.md + +Truth docs created: +- docs/truthmark/engineering/contracts/routing.md + +Truth docs updated: +- docs/truthmark/engineering/behaviors/check-diagnostics.md + +Truth docs restructured: +- docs/truthmark/engineering/behaviors/check-diagnostics.md + +Routing updated: +- docs/truthmark/routes/areas.md + +Evidence checked: +- Claim: Route resolution behavior is documented in the contracts truth doc. + Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9 + Result: supported + +Notes: +- Documented routing and behavior from route handlers and tests. +``` diff --git a/.cursor/rules/truthmark-realize.mdc b/.cursor/rules/truthmark-realize.mdc new file mode 100644 index 0000000..363e46e --- /dev/null +++ b/.cursor/rules/truthmark-realize.mdc @@ -0,0 +1,76 @@ +--- +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. +alwaysApply: false +--- + +# Truthmark Realize + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Cursor entrypoint for Truthmark Realize. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-realize + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then read tests and the relevant functional code. +3. 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. +Truth-doc ownership review: +- 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, stop before writing code and recommend Truth Structure or Truth Document +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff 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 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 + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs + +## Report Template + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` diff --git a/.cursor/rules/truthmark-structure.mdc b/.cursor/rules/truthmark-structure.mdc new file mode 100644 index 0000000..95cb42d --- /dev/null +++ b/.cursor/rules/truthmark-structure.mdc @@ -0,0 +1,155 @@ +--- +description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. +alwaysApply: false +--- + +# Truthmark Structure + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Cursor entrypoint for Truthmark Structure. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-structure + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +Description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. + +## Procedure + +Use this skill to design or repair Truthmark area structure. + +Truth Structure is agent-native: +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- 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: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document + - 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. +- 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 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 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. + +- 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 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. +Do: +- inspect the named code area +- infer bounded product or behavior ownership +- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review +- create or update the child route entry or file +- create starter truth docs only where current truth is missing +- report the initial truth boundary +Do not: +- do not edit functional code +- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it +- do not patch broad or mixed-owner docs in place +- do not create generic catch-all docs +- do not treat README files as Sync targets +## 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 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 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 +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 +- either configured lane 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 truth doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/** +Use these review thresholds as guidance: +- 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 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 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//.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 +- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +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 +- 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, 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. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +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. + +## Report Template + +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- product docs root: docs/truthmark/product +- engineering docs root: docs/truthmark/engineering +- route files: docs/truthmark/routes/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/routes/areas.md +Initial truth boundary: +- Area: Authentication +- Code: src/auth/** +- Product owner: docs/truthmark/product/capabilities/authentication-session.md +- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md +- Scope: session behavior only +Truth docs created: +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md +Truth docs split: +- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md +Truth docs restructured: +- docs/truthmark/truth/authentication/README.md +Evidence checked: +- Claim: Session behavior belongs to a dedicated Authentication truth owner. + Evidence: src/auth/** / docs/truthmark/routes/areas.md:7 + Result: supported +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.cursor/rules/truthmark-sync.mdc b/.cursor/rules/truthmark-sync.mdc new file mode 100644 index 0000000..750d1e3 --- /dev/null +++ b/.cursor/rules/truthmark-sync.mdc @@ -0,0 +1,131 @@ +--- +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. +alwaysApply: false +--- + +# Truthmark Sync + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +This rule is the Cursor entrypoint for Truthmark Sync. + +Do not invoke another Truthmark command from here. + +Manual invocation: @truthmark-sync + +If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure. + +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. + +## Procedure + +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. +Explicit invocation runs immediately when the user directly requests this workflow. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. 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. +5. Product truth decision: + - ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed + - if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering + - if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes + - when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes + - when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document +6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff. +7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence. +8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +9. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +10. Fill Sync Intent before editing truth docs or truth routing files: + - Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected + - Affected route/truth owner: bounded route area or canonical truth owner that maps the change + - Target truth docs: docs expected to change, or docs reviewed and left unchanged + - Intended update: claim/doc/routing update planned before writing + - Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff + - 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, 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, 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 +- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes +Optional validation tooling: +- you may run truthmark check when local tooling is available +- you may validate the final report with `truthmark validate sync-report --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 +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 +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 +- 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 +- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files + +## Report Template + +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Sync Intent: +- Changed code reviewed: src/auth/session.ts +- Affected route/truth owner: docs/truthmark/routes/areas.md +- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md +- Intended update: Update session timeout behavior. +- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 +- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency +- No-update-needed rationale: not applicable; mapped truth is stale +- Blockers: none + +Ownership reviewed: +- docs/truthmark/routes/areas.md + +Truth docs updated: +- docs/truthmark/engineering/repository/bootstrap-routing.md + +Decision/rationale captured: +- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale. + +Evidence checked: +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 + Result: supported + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/routes/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/README.md b/README.md index b8af488..33c4367 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ truthmark: enabled: false ``` -Then install the repo-local truth docs, routing, and agent workflow surfaces: +Then install the repo-local truth docs, routing, and AI-host instructions: ```bash truthmark init @@ -69,7 +69,7 @@ Truthmark isn't just another documentation tool. It is deeply integrated into th * **🚫 Zero Vendor Lock-in:** No hosted services, no hidden databases, no extra servers to operate. * **🌳 100% Git-Native:** Everything lives in your repository. The truth moves with your branch. -* **🤝 Dual-Surface Architecture:** It cleanly separates the tools humans use to manage the repo from the workflows AI agents use to write code. +* **🤝 Human-owned, agent-followed contract:** Maintainers own the repo contract; agents follow the installed instructions while coding. * **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff. ## 🔄 How It Works @@ -78,27 +78,40 @@ When an AI agent modifies your code, the job isn't finished. Truthmark installs 1. 💻 **Code:** Agent modifies functional code. 2. 🧪 **Test:** Relevant tests are executed. -3. 🔍 **Check:** `Truth Sync` checks mapped documentation when the installed workflow runs. +3. 🔍 **Check:** Truthmark checks mapped documentation as part of the installed finish-time review. 4. 📝 **Document:** Docs are updated by the agent when repository truth has changed. 5. 👀 **Review:** A human reviews the *code diff* + the *truth diff*. -## 🛠 Two Surfaces, One Truth System +## 🛠 How you interact with Truthmark -Truthmark is intentionally split into two distinct surfaces to serve both human maintainers and AI agents. +Truthmark has one repo-local contract with two ways to use it. -### 1. 🧑‍💻 The Human CLI (Maintainers & CI) -Used by developers to set up, configure, and validate the repository. -* `truthmark config` - Creates your initial configuration. -* `truthmark init` - Installs the necessary routing, scaffolds, and instructions. -* `truthmark check` - Validates truth artifacts from the terminal. +### Humans install and validate the contract -### 2. 🤖 The AI-Facing Workflows (Agents) -Truthmark installs native skills, prompts, and commands that supported AI hosts (like Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor) understand. These are *not* shell commands; they are workflow entry points for the AI. -* `/truthmark-sync` - The finish-time workflow agents follow after functional code changes; not a normal user-start command. -* `/truthmark-document` - Generate docs for undocumented existing code. -* `/truthmark-structure` - Organize broad repository areas into specific domains. -* `/truthmark-realize` - **Doc-First Development:** Read architecture docs and generate code to match. -* `/truthmark-check` - Agent-driven audit of the repository's truth. +Maintainers and CI use the CLI: + +* `truthmark config` - create the initial configuration. +* `truthmark init` - install or refresh routing, truth-doc scaffolds, and AI-host instructions. +* `truthmark check` - validate the repository truth from the terminal. + +### Agents follow the contract while coding + +Truthmark installs repo-local instructions for supported AI coding hosts such as Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor. + +The normal loop is simple: + +1. Ask your agent for a code change, or ask it to document existing behavior. +2. The installed instructions tell the agent when to test, when to update truth docs, and when to stop for human review. +3. You review ordinary Git diffs: code plus any truth-doc changes. + +The user-started agent requests are intentionally few: + +* `/truthmark-document` - document existing implemented behavior from code and tests. +* `/truthmark-realize` - implement code from existing truth docs. +* `/truthmark-check` - audit repository truth. + +Truth Sync is not the usual way to start work; it is the finish-time review after functional code changes. +Truth Structure is not a day-to-day command; it repairs routing or ownership only when that blocks the work. ## What you get @@ -107,7 +120,7 @@ Truthmark installs native skills, prompts, and commands that supported AI hosts | 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, realization, and audit. | +| Installed agent guidance | Tells coding agents when to document, test, sync truth, audit, or stop for review. | | 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. | @@ -119,7 +132,7 @@ Truthmark installs native skills, prompts, and commands that supported AI hosts ![Truthmark features](docs/assets/truthmark-features.png) -**Features:** what Truthmark installs and how the workflow surface is split. +**Features:** what Truthmark installs and how agents use repo-local instructions. ![Truthmark position](docs/assets/truthmark-position.png) @@ -150,7 +163,7 @@ It is useful when you need: - explicit ownership between docs and code - safer agent write boundaries - reviewable documentation instead of hidden memory -- AI workflows that still work from committed repo files +- agent guidance that still works from committed repo files ## Where Truthmark fits @@ -172,7 +185,7 @@ Truthmark’s lane is narrow by design: ```text make repository truth explicit route it to code -install agent workflows around it +install agent guidance around it keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ For command-by-command usage, surface comparisons, supported platform details, c The current release provides: - local CLI commands for config, init, check, index, impact, and workflow status -- generated AI workflow surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor +- generated repo-local agent instructions for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor - route, authority, frontmatter, link, freshness, generated-surface, branch-scope, and coverage diagnostics - branch-scoped truth docs and derived repository-intelligence artifacts diff --git a/docs/readmes/README.ar.md b/docs/readmes/README.ar.md index 4a26a7d..0f2ab60 100644 --- a/docs/readmes/README.ar.md +++ b/docs/readmes/README.ar.md @@ -69,7 +69,7 @@ Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق * **🚫 بلا ارتباط بمورّد واحد:** لا خدمات مستضافة، ولا قواعد بيانات مخفية، ولا خوادم إضافية للتشغيل. * **🌳 أصلي 100% لـ Git:** كل شيء يعيش في مستودعك. تنتقل الحقيقة مع فرعك. -* **🤝 معمارية بسطحين:** تفصل بوضوح بين الأدوات التي يستخدمها البشر لإدارة المستودع ومسارات العمل التي يستخدمها وكلاء الذكاء الاصطناعي لكتابة الكود. +* **🤝 عقد يملكه البشر ويتبعه الوكلاء:** الصائنون يملكون عقد المستودع؛ والوكلاء يتبعون التعليمات المثبّتة أثناء البرمجة. * **✅ الثقة عبر التحقق:** يصبح عمل الذكاء الاصطناعي أسهل للثقة لأن العمل الذي يغيّر السلوك يتضمن قراراً أو فرقاً في توثيق الحقيقة يمكن للبشر مراجعته. ## 🔄 كيف يعمل @@ -78,29 +78,40 @@ Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق 1. 💻 **الكود:** يغيّر الوكيل الكود الوظيفي. 2. 🧪 **الاختبار:** تُشغّل الاختبارات ذات الصلة. -3. 🔍 **التحقق:** يتحقق `Truth Sync` من التوثيق المربوط عندما يعمل سير العمل المثبّت. +3. 🔍 **التحقق:** يتحقق Truthmark من التوثيق المربوط كجزء من مراجعة وقت الإنهاء المثبّتة. 4. 📝 **التوثيق:** يحدّث الوكيل الوثائق عندما تتغير حقيقة المستودع. 5. 👀 **المراجعة:** يراجع إنسان *فرق الكود* + *فرق الحقيقة*. -## 🛠 سطحان، نظام حقيقة واحد +## 🛠 كيف تتفاعل مع Truthmark -ينقسم Truthmark عمداً إلى سطحين متميزين لخدمة صائني المشروع البشر ووكلاء الذكاء الاصطناعي معاً. +لدى Truthmark عقد واحد محلي داخل المستودع، وطريقتان لاستخدامه. -### 1. 🧑‍💻 واجهة CLI البشرية (الصائنون وCI) +### البشر يثبّتون العقد ويتحققون منه -يستخدمها المطورون لإعداد المستودع وتهيئته والتحقق منه. -* `truthmark config` - ينشئ إعداداتك الأولية. -* `truthmark init` - يثبّت التوجيه والهياكل والتعليمات اللازمة. -* `truthmark check` - يتحقق من عناصر الحقيقة من الطرفية. +يستخدم الصائنون وCI واجهة CLI: -### 2. 🤖 مسارات العمل الموجّهة للذكاء الاصطناعي (الوكلاء) +* `truthmark config` - إنشاء الإعدادات الأولية. +* `truthmark init` - تثبيت أو تحديث التوجيه، وقوالب وثائق الحقيقة، وتعليمات مضيف الذكاء الاصطناعي. +* `truthmark check` - التحقق من حقيقة المستودع من الطرفية. -يثبّت Truthmark مهارات ومطالبات وأوامر أصلية تفهمها مضيفات الذكاء الاصطناعي المدعومة (مثل Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor). هذه *ليست* أوامر shell؛ إنها نقاط دخول لسير العمل مخصصة للذكاء الاصطناعي. -* `/truthmark-sync` - سير عمل وقت الإنهاء الذي يتبعه الوكلاء بعد تغييرات الكود الوظيفي؛ ليس أمراً عادياً يبدأه المستخدم. -* `/truthmark-document` - يولّد وثائق لكود موجود غير موثّق. -* `/truthmark-structure` - ينظم مناطق المستودع الواسعة في نطاقات محددة. -* `/truthmark-realize` - **التطوير وفق التوثيق أولاً:** يقرأ وثائق المعمارية ويولّد كوداً يطابقها. -* `/truthmark-check` - تدقيق يقوده الوكيل لحقيقة المستودع. +### الوكلاء يتبعون العقد أثناء البرمجة + +يثبّت Truthmark تعليمات محلية في المستودع لمضيفي البرمجة بالذكاء الاصطناعي المدعومين مثل Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor. + +الحلقة العادية بسيطة: + +1. اطلب من الوكيل تغيير كود، أو اطلب منه توثيق سلوك موجود. +2. تخبر التعليمات المثبّتة الوكيل متى يختبر، ومتى يحدّث وثائق الحقيقة، ومتى يتوقف للمراجعة البشرية. +3. أنت تراجع فروق Git العادية: الكود وأي تغييرات في وثائق الحقيقة. + +طلبات الوكيل التي يبدأها المستخدم قليلة عمداً: + +* `/truthmark-document` - توثيق سلوك منفّذ موجود من الكود والاختبارات. +* `/truthmark-realize` - تنفيذ الكود من وثائق الحقيقة الموجودة. +* `/truthmark-check` - تدقيق حقيقة المستودع. + +Truth Sync ليس الطريقة المعتادة لبدء العمل؛ إنه مراجعة وقت الإنهاء بعد تغييرات الكود الوظيفية. +Truth Structure ليس أمراً يومياً؛ إنه يصلح التوجيه أو الملكية فقط عندما يعيق ذلك العمل. ## ما الذي تحصل عليه @@ -109,7 +120,7 @@ Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق | حقيقة أصلية لـ Git | تُبقي حقيقة المستودع في Markdown وإعدادات ملتزم بها. | | توثيق مرتبط بالفرع | تنتقل الحقيقة مع الفرع بدلاً من العيش في جلسة خاصة. | | CLI بشري | يمنح الصائنين أوامر للإعداد والتحديث والتحقق والفحص. | -| مسارات عمل موجهة للذكاء الاصطناعي | يمنح الوكلاء مسارات عمل أصلية للمضيف للمزامنة والتوثيق والهيكلة والتحقيق والتدقيق. | +| إرشادات الوكيل المثبّتة | تخبر وكلاء البرمجة متى يوثقون، أو يختبرون، أو يزامنون الحقيقة، أو يدققون، أو يتوقفون للمراجعة. | | توجيه صريح | يربط مناطق الكود بوثائق الحقيقة المعتمدة. | | تسليمات قابلة للمراجعة | ينتج فروق Git عادية لكل من الكود ووثائق الحقيقة. | | تشغيل محلي أولاً | لا يتطلب خدمة مستضافة أو daemon أو قاعدة بيانات أو خادم MCP. | @@ -174,7 +185,7 @@ Truthmark مخصص للفرق التي تعرف بالفعل أن وكلاء ا ```text make repository truth explicit route it to code -install agent workflows around it +تثبيت إرشادات الوكلاء حولها keep the result reviewable in Git ``` @@ -189,7 +200,7 @@ README هو الواجهة: سياق سريع، وبدء سريع، والنمو يوفر الإصدار الحالي: - أوامر CLI محلية للإعداد والتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل -- أسطح سير عمل ذكاء اصطناعي مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor +- تعليمات وكلاء محلية مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor - تشخيصات للتوجيه والسلطة وfrontmatter والروابط والحداثة والأسطح المولّدة ونطاق الفرع والتغطية - وثائق حقيقة مرتبطة بالفرع وعناصر مستمدة لاستخبارات المستودع diff --git a/docs/readmes/README.de.md b/docs/readmes/README.de.md index 0d59c5f..df772a0 100644 --- a/docs/readmes/README.de.md +++ b/docs/readmes/README.de.md @@ -29,7 +29,7 @@ truthmark: enabled: false ``` -Installiere anschließend die repo-lokalen Truth-Dokumente, das Routing und die Agent-Workflow-Oberflächen: +Installiere anschließend die repo-lokalen Truth-Dokumente, das Routing und die Anweisungen für KI-Hosts: ```bash truthmark init @@ -69,7 +69,7 @@ Truthmark ist nicht einfach nur ein weiteres Dokumentationstool. Es ist tief in * **🚫 Kein Vendor-Lock-in:** keine gehosteten Dienste, keine versteckten Datenbanken, keine zusätzlichen Server im Betrieb. * **🌳 100 % Git-nativ:** alles lebt in deinem Repository. Die Wahrheit bewegt sich mit deinem Branch. -* **🤝 Architektur mit zwei Oberflächen:** es trennt sauber die Werkzeuge, mit denen Menschen das Repo verwalten, von den Workflows, mit denen KI-Agenten Code schreiben. +* **🤝 Von Menschen besessener, von Agenten befolgter Vertrag:** Maintainer besitzen den Repository-Vertrag; Agenten folgen beim Coden den installierten Anweisungen. * **✅ Vertrauen durch Verifikation:** KI-Arbeit wird leichter vertrauenswürdig, weil verhaltensändernde Arbeit eine für Menschen überprüfbare Truth-Doc-Entscheidung oder einen Diff enthält. ## 🔄 Wie es funktioniert @@ -78,27 +78,40 @@ Wenn ein KI-Agent deinen Code verändert, ist die Arbeit nicht erledigt. Truthma 1. 💻 **Code:** Der Agent ändert funktionalen Code. 2. 🧪 **Test:** Relevante Tests werden ausgeführt. -3. 🔍 **Prüfung:** `Truth Sync` prüft zugeordnete Dokumentation, wenn der installierte Workflow läuft. +3. 🔍 **Prüfen:** Truthmark prüft zugeordnete Dokumentation als Teil der installierten Abschlussprüfung. 4. 📝 **Dokumentation:** Docs werden vom Agenten aktualisiert, wenn sich die Repository-Wahrheit geändert hat. 5. 👀 **Review:** Ein Mensch prüft den *Code-Diff* + den *Truth-Diff*. -## 🛠 Zwei Oberflächen, ein Truth-System +## 🛠 Wie du mit Truthmark interagierst -Truthmark ist bewusst in zwei getrennte Oberflächen aufgeteilt, um sowohl menschliche Maintainer als auch KI-Agenten zu unterstützen. +Truthmark hat einen repo-lokalen Vertrag und zwei Arten, ihn zu nutzen. -### 1. 🧑‍💻 Die menschliche CLI (Maintainer & CI) -Wird von Entwicklern verwendet, um das Repository einzurichten, zu konfigurieren und zu validieren. -* `truthmark config` - erstellt deine Anfangskonfiguration. -* `truthmark init` - installiert das notwendige Routing, Scaffolding und die Anweisungen. -* `truthmark check` - validiert Truth-Artefakte vom Terminal aus. +### Menschen installieren und validieren den Vertrag -### 2. 🤖 Die KI-seitigen Workflows (Agenten) -Truthmark installiert native Skills, Prompts und Befehle, die unterstützte KI-Hosts (wie Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor) verstehen. Das sind *keine* Shell-Befehle; es sind Workflow-Einstiegspunkte für die KI. -* `/truthmark-sync` - der Abschluss-Workflow, dem Agenten nach funktionalen Codeänderungen folgen; kein normaler, vom Nutzer gestarteter Befehl. -* `/truthmark-document` - erzeugt Docs für undokumentierten bestehenden Code. -* `/truthmark-structure` - organisiert breite Repository-Bereiche in spezifische Domänen. -* `/truthmark-realize` - **Doc-First-Entwicklung:** liest Architekturdokumente und erzeugt passenden Code. -* `/truthmark-check` - agentengesteuertes Audit der Repository-Wahrheit. +Maintainer und CI nutzen die CLI: + +* `truthmark config` - erstellt die Anfangskonfiguration. +* `truthmark init` - installiert oder aktualisiert Routing, Truth-Doc-Scaffolds und Anweisungen für KI-Hosts. +* `truthmark check` - validiert die Repository-Truth im Terminal. + +### Agenten folgen dem Vertrag beim Coden + +Truthmark installiert repo-lokale Anweisungen für unterstützte KI-Coding-Hosts wie Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor. + +Der normale Ablauf ist einfach: + +1. Bitte deinen Agenten um eine Codeänderung oder darum, vorhandenes Verhalten zu dokumentieren. +2. Die installierten Anweisungen sagen dem Agenten, wann er testen, wann er Truth-Dokumente aktualisieren und wann er für menschliche Prüfung stoppen soll. +3. Du prüfst normale Git-Diffs: Code plus alle Truth-Doc-Änderungen. + +Die vom Nutzer gestarteten Agentenanfragen bleiben bewusst wenige: + +* `/truthmark-document` - dokumentiert vorhandenes implementiertes Verhalten aus Code und Tests. +* `/truthmark-realize` - implementiert Code aus vorhandenen Truth-Dokumenten. +* `/truthmark-check` - auditiert die Repository-Truth. + +Truth Sync ist nicht der übliche Weg, Arbeit zu starten; es ist die Abschlussprüfung nach funktionalen Codeänderungen. +Truth Structure ist kein Alltagsbefehl; es repariert Routing oder Ownership nur, wenn das die Arbeit blockiert. ## Was du bekommst @@ -107,7 +120,7 @@ Truthmark installiert native Skills, Prompts und Befehle, die unterstützte KI-H | Git-native Wahrheit | Hält Repository-Wahrheit in committetem Markdown und Konfiguration. | | Branch-bezogene Dokumentation | Die Wahrheit bewegt sich mit dem Branch, statt in einer privaten Sitzung zu leben. | | Menschliche CLI | Gibt Maintainern Befehle für Einrichtung, Aktualisierung, Validierung und Inspektion. | -| KI-seitige Workflows | Gibt Agenten host-native Workflows für Sync, Dokumentation, Struktur, Realisierung und Audit. | +| Installierte Agentenanleitung | Sagt Coding-Agenten, wann sie dokumentieren, testen, Truth synchronisieren, auditieren oder für Review stoppen sollen. | | Explizites Routing | Ordnet Codebereiche kanonischen Truth-Dokumenten zu. | | Überprüfbare Übergaben | Erzeugt normale Git-Diffs sowohl für Code als auch für Truth-Dokumente. | | Local-first-Betrieb | Benötigt keinen gehosteten Dienst, Daemon, keine Datenbank und keinen MCP-Server. | @@ -119,7 +132,7 @@ Truthmark installiert native Skills, Prompts und Befehle, die unterstützte KI-H ![Truthmark-Funktionen](../assets/truthmark-features.png) -**Funktionen:** was Truthmark installiert und wie die Workflow-Oberfläche aufgeteilt ist. +**Funktionen:** was Truthmark installiert und wie Agenten repo-lokale Anweisungen nutzen. ![Truthmark-Position](../assets/truthmark-position.png) @@ -150,7 +163,7 @@ Es ist nützlich, wenn du Folgendes brauchst: - explizite Ownership zwischen Docs und Code - sicherere Schreibgrenzen für Agenten - überprüfbare Dokumentation statt versteckter Memory -- KI-Workflows, die weiterhin aus committeten Repo-Dateien funktionieren +- Agentenanleitung, die weiterhin aus committeten Repo-Dateien funktioniert ## Wo Truthmark hineinpasst @@ -172,7 +185,7 @@ Truthmarks Spur ist bewusst schmal: ```text make repository truth explicit route it to code -install agent workflows around it +Agentenanleitung darum installieren keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ Für befehlsweise Nutzung, Oberflächenvergleiche, Details zu unterstützten Pla Die aktuelle Version bietet: - lokale CLI-Befehle für config, init, check, index, impact und Workflow-Status -- generierte KI-Workflow-Oberflächen für Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor +- generierte repo-lokale Agentenanweisungen für Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor - Diagnosen für Routing, Autorität, Frontmatter, Links, Aktualität, generierte Oberflächen, Branch-Scope und Abdeckung - branch-bezogene Truth-Dokumente und abgeleitete Repository-Intelligence-Artefakte diff --git a/docs/readmes/README.el.md b/docs/readmes/README.el.md index ac88cdc..ea68da5 100644 --- a/docs/readmes/README.el.md +++ b/docs/readmes/README.el.md @@ -69,7 +69,7 @@ git diff * **🚫 Μηδενικό κλείδωμα σε προμηθευτή:** Καμία hosted υπηρεσία, καμία κρυφή βάση δεδομένων, κανένας επιπλέον server προς λειτουργία. * **🌳 100% Git-native:** Όλα ζουν στο αποθετήριό σας. Η αλήθεια κινείται μαζί με το branch σας. -* **🤝 Αρχιτεκτονική δύο επιφανειών:** Διαχωρίζει καθαρά τα εργαλεία που χρησιμοποιούν οι άνθρωποι για τη διαχείριση του repo από τις ροές εργασίας που χρησιμοποιούν οι AI agents για να γράφουν κώδικα. +* **🤝 Συμβόλαιο που ανήκει σε ανθρώπους και ακολουθείται από agents:** Οι συντηρητές κατέχουν το συμβόλαιο του αποθετηρίου· οι agents ακολουθούν τις εγκατεστημένες οδηγίες ενώ γράφουν κώδικα. * **✅ Εμπιστοσύνη μέσω επαλήθευσης:** Η εργασία AI γίνεται ευκολότερο να εμπιστευτεί, επειδή η εργασία που αλλάζει συμπεριφορά περιλαμβάνει μια απόφαση ή ένα diff εγγράφου αλήθειας που μπορεί να ελεγχθεί από άνθρωπο. ## 🔄 Πώς λειτουργεί @@ -78,29 +78,40 @@ git diff 1. 💻 **Κώδικας:** Ο πράκτορας τροποποιεί λειτουργικό κώδικα. 2. 🧪 **Test:** Εκτελούνται τα σχετικά tests. -3. 🔍 **Έλεγχος:** Το `Truth Sync` ελέγχει την αντιστοιχισμένη τεκμηρίωση όταν εκτελείται η εγκατεστημένη ροή εργασίας. +3. 🔍 **Έλεγχος:** Το Truthmark ελέγχει τη χαρτογραφημένη τεκμηρίωση ως μέρος της εγκατεστημένης τελικής ανασκόπησης. 4. 📝 **Τεκμηρίωση:** Τα docs ενημερώνονται από τον πράκτορα όταν αλλάζει η αλήθεια του αποθετηρίου. 5. 👀 **Ανασκόπηση:** Ένας άνθρωπος ανασκοπεί το *code diff* + το *diff αλήθειας*. -## 🛠 Δύο επιφάνειες, ένα σύστημα αλήθειας +## 🛠 Πώς αλληλεπιδράτε με το Truthmark -Το Truthmark χωρίζεται σκόπιμα σε δύο ξεχωριστές επιφάνειες για να εξυπηρετεί τόσο τους ανθρώπους συντηρητές όσο και τους AI agents. +Το Truthmark έχει ένα repo-local συμβόλαιο και δύο τρόπους χρήσης του. -### 1. 🧑‍💻 Το ανθρώπινο CLI (συντηρητές & CI) +### Οι άνθρωποι εγκαθιστούν και επικυρώνουν το συμβόλαιο -Χρησιμοποιείται από developers για τη ρύθμιση, τη διαμόρφωση και την επικύρωση του αποθετηρίου. -* `truthmark config` - Δημιουργεί την αρχική σας διαμόρφωση. -* `truthmark init` - Εγκαθιστά την απαραίτητη δρομολόγηση, τα scaffolds και τις οδηγίες. -* `truthmark check` - Επικυρώνει τα τεχνουργήματα αλήθειας από το terminal. +Οι συντηρητές και το CI χρησιμοποιούν το CLI: -### 2. 🤖 Οι ροές εργασίας που απευθύνονται στην AI (πράκτορες) +* `truthmark config` - δημιουργεί την αρχική διαμόρφωση. +* `truthmark init` - εγκαθιστά ή ανανεώνει routing, truth-doc scaffolds και οδηγίες για AI hosts. +* `truthmark check` - επικυρώνει την αλήθεια του αποθετηρίου από το τερματικό. -Το Truthmark εγκαθιστά native skills, prompts και εντολές που καταλαβαίνουν οι υποστηριζόμενοι AI hosts (όπως Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor). Αυτά *δεν* είναι shell commands· είναι σημεία εισόδου ροών εργασίας για την AI. -* `/truthmark-sync` - Η ροή εργασίας στο τέλος που ακολουθούν οι πράκτορες μετά από αλλαγές λειτουργικού κώδικα· δεν είναι κανονική εντολή εκκίνησης χρήστη. -* `/truthmark-document` - Δημιουργεί docs για υπάρχον μη τεκμηριωμένο κώδικα. -* `/truthmark-structure` - Οργανώνει ευρείες περιοχές αποθετηρίου σε συγκεκριμένους τομείς. -* `/truthmark-realize` - **Ανάπτυξη με τεκμηρίωση πρώτα:** Διαβάζει αρχιτεκτονικά docs και δημιουργεί κώδικα που ταιριάζει. -* `/truthmark-check` - Έλεγχος της αλήθειας του αποθετηρίου που καθοδηγείται από πράκτορα. +### Οι agents ακολουθούν το συμβόλαιο ενώ γράφουν κώδικα + +Το Truthmark εγκαθιστά repo-local οδηγίες για υποστηριζόμενους AI coding hosts όπως Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor. + +Ο κανονικός κύκλος είναι απλός: + +1. Ζητήστε από τον agent αλλαγή κώδικα ή τεκμηρίωση υπάρχουσας συμπεριφοράς. +2. Οι εγκατεστημένες οδηγίες λένε στον agent πότε να δοκιμάσει, πότε να ενημερώσει truth docs και πότε να σταματήσει για ανθρώπινη ανασκόπηση. +3. Εσείς ελέγχετε κανονικά Git diffs: κώδικα και τυχόν αλλαγές σε truth docs. + +Τα user-started αιτήματα προς agents είναι σκόπιμα λίγα: + +* `/truthmark-document` - τεκμηριώνει υπάρχουσα υλοποιημένη συμπεριφορά από κώδικα και tests. +* `/truthmark-realize` - υλοποιεί κώδικα από υπάρχοντα truth docs. +* `/truthmark-check` - ελέγχει την αλήθεια του αποθετηρίου. + +Το Truth Sync δεν είναι ο συνηθισμένος τρόπος έναρξης εργασίας· είναι η τελική ανασκόπηση μετά από λειτουργικές αλλαγές κώδικα. +Το Truth Structure δεν είναι καθημερινή εντολή· επισκευάζει routing ή ownership μόνο όταν αυτό μπλοκάρει την εργασία. ## Τι παίρνετε @@ -109,7 +120,7 @@ git diff | Git-native αλήθεια | Διατηρεί την αλήθεια του αποθετηρίου σε committed Markdown και config. | | Τεκμηρίωση με scope branch | Η αλήθεια κινείται με το branch αντί να ζει σε ιδιωτική session. | | Ανθρώπινο CLI | Δίνει στους συντηρητές εντολές setup, refresh, validation και inspection. | -| Ροές εργασίας για AI | Δίνει στους πράκτορες host-native ροές εργασίας για sync, documentation, structure, realization και audit. | +| Εγκατεστημένη καθοδήγηση agent | Λέει στους coding agents πότε να τεκμηριώσουν, να δοκιμάσουν, να συγχρονίσουν truth, να κάνουν audit ή να σταματήσουν για review. | | Ρητή δρομολόγηση | Αντιστοιχίζει περιοχές κώδικα σε κανονικά έγγραφα αλήθειας. | | Ελέγξιμες παραδόσεις | Παράγει συνηθισμένα Git diffs τόσο για κώδικα όσο και για έγγραφα αλήθειας. | | Local-first λειτουργία | Δεν απαιτεί hosted service, daemon, βάση δεδομένων ή MCP server. | @@ -152,7 +163,7 @@ git diff - ρητή ιδιοκτησία μεταξύ docs και code - ασφαλέστερα όρια εγγραφής πρακτόρων - ελέγξιμη τεκμηρίωση αντί για κρυφή μνήμη -- AI workflows που συνεχίζουν να λειτουργούν από committed repo files +- καθοδήγηση για agents που εξακολουθεί να λειτουργεί από committed αρχεία του repo ## Πού ταιριάζει το Truthmark @@ -174,7 +185,7 @@ git diff ```text make repository truth explicit route it to code -install agent workflows around it +εγκατάσταση καθοδήγησης για agents γύρω από αυτή keep the result reviewable in Git ``` @@ -189,7 +200,7 @@ keep the result reviewable in Git Η τρέχουσα έκδοση παρέχει: - τοπικές CLI commands για config, init, check, index, impact και workflow status -- generated AI workflow surfaces για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor +- παραγόμενες repo-local οδηγίες για agents για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor - diagnostics για route, authority, frontmatter, link, freshness, generated-surface, branch-scope και coverage - έγγραφα αλήθειας με scope branch και παράγωγα τεχνουργήματα ευφυΐας αποθετηρίου diff --git a/docs/readmes/README.es.md b/docs/readmes/README.es.md index e95bb13..0b34e82 100644 --- a/docs/readmes/README.es.md +++ b/docs/readmes/README.es.md @@ -29,7 +29,7 @@ truthmark: enabled: false ``` -Después instala los documentos de verdad locales del repositorio, el enrutamiento y las superficies de workflow para agentes: +Después instala los documentos de verdad locales del repositorio, el enrutamiento y las instrucciones para hosts de IA: ```bash truthmark init @@ -69,7 +69,7 @@ Truthmark no es simplemente otra herramienta de documentación. Está profundame * **🚫 Sin dependencia de proveedor:** no hay servicios alojados, bases de datos ocultas ni servidores adicionales que operar. * **🌳 100 % nativo de Git:** todo vive en tu repositorio. La verdad se mueve con tu rama. -* **🤝 Arquitectura de dos superficies:** separa limpiamente las herramientas que las personas usan para gestionar el repositorio de los workflows que los agentes de IA usan para escribir código. +* **🤝 Contrato propiedad de humanos y seguido por agentes:** Los mantenedores poseen el contrato del repositorio; los agentes siguen las instrucciones instaladas mientras programan. * **✅ Confianza mediante verificación:** el trabajo de la IA resulta más fácil de confiar porque el trabajo que cambia comportamiento incluye una decisión o un diff de documento de verdad revisable por humanos. ## 🔄 Cómo funciona @@ -78,27 +78,40 @@ Cuando un agente de IA modifica tu código, el trabajo no ha terminado. Truthmar 1. 💻 **Código:** el agente modifica código funcional. 2. 🧪 **Prueba:** se ejecutan las pruebas pertinentes. -3. 🔍 **Comprobación:** `Truth Sync` comprueba la documentación mapeada cuando se ejecuta el workflow instalado. +3. 🔍 **Comprobación:** Truthmark revisa la documentación mapeada como parte de la revisión de cierre instalada. 4. 📝 **Documentación:** el agente actualiza los docs cuando la verdad del repositorio ha cambiado. 5. 👀 **Revisión:** una persona revisa el *diff de código* + el *diff de verdad*. -## 🛠 Dos superficies, un sistema de verdad +## 🛠 Cómo interactúas con Truthmark -Truthmark se divide intencionadamente en dos superficies distintas para servir tanto a mantenedores humanos como a agentes de IA. +Truthmark tiene un contrato local del repositorio y dos formas de usarlo. -### 1. 🧑‍💻 La CLI humana (mantenedores y CI) -La usan los desarrolladores para preparar, configurar y validar el repositorio. -* `truthmark config` - crea tu configuración inicial. -* `truthmark init` - instala el enrutamiento, los andamios y las instrucciones necesarios. -* `truthmark check` - valida artefactos de verdad desde la terminal. +### Las personas instalan y validan el contrato -### 2. 🤖 Los workflows orientados a la IA (agentes) -Truthmark instala skills, prompts y comandos nativos que entienden los hosts de IA compatibles (como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor). Estos *no* son comandos de shell; son puntos de entrada de workflow para la IA. -* `/truthmark-sync` - el workflow de cierre que siguen los agentes después de cambios de código funcional; no es un comando normal iniciado por el usuario. -* `/truthmark-document` - genera docs para código existente no documentado. -* `/truthmark-structure` - organiza áreas amplias del repositorio en dominios específicos. -* `/truthmark-realize` - **Desarrollo doc-first:** lee docs de arquitectura y genera código que coincida. -* `/truthmark-check` - auditoría de la verdad del repositorio dirigida por el agente. +Los mantenedores y CI usan la CLI: + +* `truthmark config` - crea la configuración inicial. +* `truthmark init` - instala o actualiza el enrutamiento, los andamios de documentos de verdad y las instrucciones para hosts de IA. +* `truthmark check` - valida la verdad del repositorio desde la terminal. + +### Los agentes siguen el contrato mientras programan + +Truthmark instala instrucciones locales del repositorio para hosts de codificación con IA compatibles, como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor. + +El ciclo normal es simple: + +1. Pide a tu agente un cambio de código o que documente un comportamiento existente. +2. Las instrucciones instaladas le dicen al agente cuándo probar, cuándo actualizar documentos de verdad y cuándo detenerse para revisión humana. +3. Revisas diffs Git normales: código más cualquier cambio en documentos de verdad. + +Las solicitudes de agente iniciadas por el usuario son deliberadamente pocas: + +* `/truthmark-document` - documenta comportamiento implementado existente a partir de código y tests. +* `/truthmark-realize` - implementa código a partir de documentos de verdad existentes. +* `/truthmark-check` - audita la verdad del repositorio. + +Truth Sync no es la forma habitual de iniciar trabajo; es la revisión de cierre después de cambios funcionales de código. +Truth Structure no es un comando cotidiano; repara enrutamiento o propiedad solo cuando eso bloquea el trabajo. ## Lo que obtienes @@ -107,7 +120,7 @@ Truthmark instala skills, prompts y comandos nativos que entienden los hosts de | Verdad nativa de Git | Mantiene la verdad del repositorio en Markdown y configuración versionados. | | Documentación con alcance de rama | La verdad se mueve con la rama en lugar de vivir en una sesión privada. | | CLI humana | Da a los mantenedores comandos de configuración, actualización, validación e inspección. | -| Workflows orientados a la IA | Da a los agentes workflows nativos del host para sincronización, documentación, estructura, realización y auditoría. | +| Guía de agente instalada | Indica a los agentes de codificación cuándo documentar, probar, sincronizar verdad, auditar o detenerse para revisión. | | Enrutamiento explícito | Mapea áreas de código a documentos de verdad canónicos. | | Entregas revisables | Produce diffs Git ordinarios tanto para el código como para los documentos de verdad. | | Operación local-first | No requiere servicio alojado, demonio, base de datos ni servidor MCP. | @@ -150,7 +163,7 @@ Es útil cuando necesitas: - propiedad explícita entre docs y código - límites de escritura de agentes más seguros - documentación revisable en lugar de memoria oculta -- workflows de IA que siguen funcionando desde archivos versionados del repositorio +- guía de agente que sigue funcionando desde archivos versionados del repositorio ## Dónde encaja Truthmark @@ -172,7 +185,7 @@ El carril de Truthmark es estrecho por diseño: ```text make repository truth explicit route it to code -install agent workflows around it +instalar guía de agente alrededor de ella keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ Para uso comando por comando, comparaciones de superficies, detalles de platafor La versión actual proporciona: - comandos CLI locales para config, init, check, index, impact y estado de workflows -- superficies de workflow de IA generadas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor +- instrucciones de agente locales del repositorio generadas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor - diagnósticos de enrutamiento, autoridad, frontmatter, enlaces, frescura, superficies generadas, alcance de rama y cobertura - documentos de verdad con alcance de rama y artefactos derivados de inteligencia del repositorio diff --git a/docs/readmes/README.fr.md b/docs/readmes/README.fr.md index 108fca7..8d82d0a 100644 --- a/docs/readmes/README.fr.md +++ b/docs/readmes/README.fr.md @@ -69,7 +69,7 @@ Truthmark n’est pas simplement un autre outil de documentation. Il est profond * **🚫 Zéro dépendance fournisseur :** aucun service hébergé, aucune base de données cachée, aucun serveur supplémentaire à exploiter. * **🌳 100 % natif Git :** tout vit dans votre dépôt. La vérité se déplace avec votre branche. -* **🤝 Architecture à deux surfaces :** il sépare clairement les outils que les humains utilisent pour gérer le dépôt des workflows que les agents IA utilisent pour écrire du code. +* **🤝 Contrat possédé par les humains, suivi par les agents :** Les mainteneurs possèdent le contrat du dépôt ; les agents suivent les instructions installées pendant qu’ils codent. * **✅ Confiance par la vérification :** le travail de l’IA devient plus facile à faire confiance, car tout travail qui change le comportement inclut une décision ou un diff de document de vérité vérifiable par un humain. ## 🔄 Fonctionnement @@ -78,27 +78,40 @@ Lorsqu’un agent IA modifie votre code, le travail n’est pas terminé. Truthm 1. 💻 **Code :** l’agent modifie le code fonctionnel. 2. 🧪 **Test :** les tests pertinents sont exécutés. -3. 🔍 **Vérification :** `Truth Sync` vérifie la documentation mappée lorsque le workflow installé s’exécute. +3. 🔍 **Vérifier :** Truthmark vérifie la documentation mappée dans le cadre de la revue de fin installée. 4. 📝 **Documentation :** les docs sont mises à jour par l’agent lorsque la vérité du dépôt a changé. 5. 👀 **Revue :** un humain examine le *diff de code* + le *diff de vérité*. -## 🛠 Deux surfaces, un seul système de vérité +## 🛠 Comment vous utilisez Truthmark -Truthmark est volontairement divisé en deux surfaces distinctes afin de servir à la fois les mainteneurs humains et les agents IA. +Truthmark fournit un contrat local au dépôt, avec deux façons de l’utiliser. -### 1. 🧑‍💻 La CLI humaine (mainteneurs et CI) -Utilisée par les développeurs pour configurer, paramétrer et valider le dépôt. -* `truthmark config` - crée votre configuration initiale. -* `truthmark init` - installe le routage, les échafaudages et les instructions nécessaires. -* `truthmark check` - valide les artefacts de vérité depuis le terminal. +### Les humains installent et valident le contrat -### 2. 🤖 Les workflows destinés à l’IA (agents) -Truthmark installe des skills, prompts et commandes natifs que les hôtes IA pris en charge (comme Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor) comprennent. Ce ne sont *pas* des commandes shell ; ce sont des points d’entrée de workflow pour l’IA. -* `/truthmark-sync` - le workflow de fin de tâche que les agents suivent après des changements de code fonctionnel ; ce n’est pas une commande normale lancée par l’utilisateur. -* `/truthmark-document` - génère des docs pour du code existant non documenté. -* `/truthmark-structure` - organise de larges zones du dépôt en domaines spécifiques. -* `/truthmark-realize` - **Développement doc-first :** lit les documents d’architecture et génère le code correspondant. -* `/truthmark-check` - audit de la vérité du dépôt piloté par l’agent. +Les mainteneurs et la CI utilisent la CLI : + +* `truthmark config` - crée la configuration initiale. +* `truthmark init` - installe ou actualise le routage, les échafaudages de documents de vérité et les instructions pour les hôtes IA. +* `truthmark check` - valide la vérité du dépôt depuis le terminal. + +### Les agents suivent le contrat pendant qu’ils codent + +Truthmark installe des instructions locales au dépôt pour les hôtes de codage IA pris en charge, comme Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor. + +La boucle normale est simple : + +1. Demandez à votre agent de modifier du code ou de documenter un comportement existant. +2. Les instructions installées indiquent à l’agent quand tester, quand mettre à jour les documents de vérité et quand s’arrêter pour une revue humaine. +3. Vous relisez des diffs Git ordinaires : le code plus les éventuels changements de documents de vérité. + +Les demandes agent lancées par l’utilisateur restent volontairement peu nombreuses : + +* `/truthmark-document` - documente un comportement implémenté existant à partir du code et des tests. +* `/truthmark-realize` - implémente le code à partir de documents de vérité existants. +* `/truthmark-check` - audite la vérité du dépôt. + +Truth Sync n’est pas la façon habituelle de commencer un travail ; c’est la revue de fin après des changements de code fonctionnel. +Truth Structure n’est pas une commande quotidienne ; elle répare le routage ou la propriété uniquement lorsque cela bloque le travail. ## Ce que vous obtenez @@ -107,7 +120,7 @@ Truthmark installe des skills, prompts et commandes natifs que les hôtes IA pri | Vérité native Git | Conserve la vérité du dépôt dans du Markdown et de la configuration commités. | | Documentation limitée à la branche | La vérité se déplace avec la branche au lieu de vivre dans une session privée. | | CLI humaine | Fournit aux mainteneurs des commandes de configuration, d’actualisation, de validation et d’inspection. | -| Workflows destinés à l’IA | Fournit aux agents des workflows natifs de l’hôte pour la synchronisation, la documentation, la structure, la réalisation et l’audit. | +| Guidance agent installée | Indique aux agents de codage quand documenter, tester, synchroniser la vérité, auditer ou s’arrêter pour revue. | | Routage explicite | Mappe les zones de code vers des documents de vérité canoniques. | | Remises vérifiables | Produit des diffs Git ordinaires pour le code comme pour les documents de vérité. | | Fonctionnement local d’abord | Ne nécessite aucun service hébergé, démon, base de données ni serveur MCP. | @@ -119,7 +132,7 @@ Truthmark installe des skills, prompts et commandes natifs que les hôtes IA pri ![Fonctionnalités Truthmark](../assets/truthmark-features.png) -**Fonctionnalités :** ce que Truthmark installe et comment la surface de workflow est divisée. +**Fonctionnalités :** ce que Truthmark installe et comment les agents utilisent les instructions locales au dépôt. ![Position de Truthmark](../assets/truthmark-position.png) @@ -150,7 +163,7 @@ Il est utile lorsque vous avez besoin de : - propriété explicite entre docs et code - limites d’écriture d’agents plus sûres - documentation vérifiable plutôt que mémoire cachée -- workflows IA qui fonctionnent toujours à partir des fichiers commités du dépôt +- une guidance agent qui fonctionne toujours depuis des fichiers commités dans le dépôt ## Où Truthmark se situe @@ -172,7 +185,7 @@ Le périmètre de Truthmark est étroit par conception : ```text make repository truth explicit route it to code -install agent workflows around it +installer une guidance agent autour d’elle keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ Pour l’utilisation commande par commande, les comparaisons de surfaces, les d La version actuelle fournit : - des commandes CLI locales pour config, init, check, index, impact et l’état des workflows -- des surfaces de workflow IA générées pour Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor +- instructions agent locales au dépôt générées pour Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor - des diagnostics de routage, d’autorité, de frontmatter, de liens, de fraîcheur, de surfaces générées, de portée de branche et de couverture - des documents de vérité limités à la branche et des artefacts dérivés d’intelligence du dépôt diff --git a/docs/readmes/README.id.md b/docs/readmes/README.id.md index 80b714d..8239039 100644 --- a/docs/readmes/README.id.md +++ b/docs/readmes/README.id.md @@ -69,7 +69,7 @@ Truthmark bukan sekadar alat dokumentasi lain. Ia terintegrasi mendalam ke dalam * **🚫 Tanpa ketergantungan vendor:** Tidak ada layanan ter-host, tidak ada basis data tersembunyi, tidak ada server tambahan untuk dioperasikan. * **🌳 100% native Git:** Semuanya hidup di repositori Anda. Kebenaran bergerak bersama branch Anda. -* **🤝 Arsitektur dua permukaan:** Memisahkan dengan bersih alat yang digunakan manusia untuk mengelola repositori dari alur kerja yang digunakan agen AI untuk menulis kode. +* **🤝 Kontrak yang dimiliki manusia dan diikuti agen:** Pemelihara memiliki kontrak repositori; agen mengikuti instruksi yang terpasang saat membuat kode. * **✅ Kepercayaan melalui verifikasi:** Pekerjaan AI menjadi lebih mudah dipercaya karena pekerjaan yang mengubah perilaku menyertakan keputusan atau diff dokumen kebenaran yang dapat ditinjau manusia. ## 🔄 Cara kerjanya @@ -78,29 +78,40 @@ Ketika agen AI memodifikasi kode Anda, pekerjaannya belum selesai. Truthmark mem 1. 💻 **Kode:** Agen memodifikasi kode fungsional. 2. 🧪 **Uji:** Pengujian yang relevan dijalankan. -3. 🔍 **Periksa:** `Truth Sync` memeriksa dokumentasi yang dipetakan saat alur kerja terpasang berjalan. +3. 🔍 **Periksa:** Truthmark memeriksa dokumentasi yang dipetakan sebagai bagian dari tinjauan akhir yang terpasang. 4. 📝 **Dokumentasikan:** Dokumen diperbarui oleh agen ketika kebenaran repositori berubah. 5. 👀 **Tinjau:** Manusia meninjau *diff kode* + *diff kebenaran*. -## 🛠 Dua permukaan, satu sistem kebenaran +## 🛠 Cara Anda berinteraksi dengan Truthmark -Truthmark sengaja dibagi menjadi dua permukaan berbeda untuk melayani pemelihara manusia dan agen AI. +Truthmark memiliki satu kontrak lokal repositori dengan dua cara pemakaian. -### 1. 🧑‍💻 CLI manusia (Pemelihara & CI) +### Manusia memasang dan memvalidasi kontrak -Digunakan oleh pengembang untuk menyiapkan, mengonfigurasi, dan memvalidasi repositori. -* `truthmark config` - Membuat konfigurasi awal Anda. -* `truthmark init` - Memasang perutean, kerangka, dan instruksi yang diperlukan. -* `truthmark check` - Memvalidasi artefak kebenaran dari terminal. +Pemelihara dan CI menggunakan CLI: -### 2. 🤖 Alur kerja yang menghadap AI (Agen) +* `truthmark config` - membuat konfigurasi awal. +* `truthmark init` - memasang atau menyegarkan perutean, scaffold dokumen kebenaran, dan instruksi host AI. +* `truthmark check` - memvalidasi kebenaran repositori dari terminal. -Truthmark memasang skill, prompt, dan perintah native yang dipahami host AI yang didukung (seperti Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor). Ini *bukan* perintah shell; ini adalah titik masuk alur kerja untuk AI. -* `/truthmark-sync` - Alur kerja saat penyelesaian yang diikuti agen setelah perubahan kode fungsional; bukan perintah awal pengguna yang biasa. -* `/truthmark-document` - Menghasilkan dokumen untuk kode yang sudah ada namun belum terdokumentasi. -* `/truthmark-structure` - Mengorganisasi area repositori yang luas menjadi domain tertentu. -* `/truthmark-realize` - **Pengembangan berawal dari dokumen:** Membaca dokumen arsitektur dan menghasilkan kode yang sesuai. -* `/truthmark-check` - Audit truth repositori yang digerakkan agen. +### Agen mengikuti kontrak saat membuat kode + +Truthmark memasang instruksi lokal repositori untuk host pengodean AI yang didukung seperti Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor. + +Alur normalnya sederhana: + +1. Minta agen Anda melakukan perubahan kode, atau minta ia mendokumentasikan perilaku yang sudah ada. +2. Instruksi yang terpasang memberi tahu agen kapan harus menguji, kapan memperbarui dokumen kebenaran, dan kapan berhenti untuk tinjauan manusia. +3. Anda meninjau diff Git biasa: kode plus perubahan dokumen kebenaran apa pun. + +Permintaan agen yang dimulai pengguna sengaja dibuat sedikit: + +* `/truthmark-document` - mendokumentasikan perilaku terimplementasi yang sudah ada dari kode dan pengujian. +* `/truthmark-realize` - mengimplementasikan kode dari dokumen kebenaran yang sudah ada. +* `/truthmark-check` - mengaudit kebenaran repositori. + +Truth Sync bukan cara biasa untuk memulai pekerjaan; itu adalah tinjauan akhir setelah perubahan kode fungsional. +Truth Structure bukan perintah harian; ia memperbaiki perutean atau kepemilikan hanya ketika hal itu memblokir pekerjaan. ## Yang Anda dapatkan @@ -109,7 +120,7 @@ Truthmark memasang skill, prompt, dan perintah native yang dipahami host AI yang | Kebenaran native Git | Menyimpan kebenaran repositori dalam Markdown dan konfigurasi yang di-commit. | | Dokumentasi berlingkup branch | Kebenaran bergerak bersama branch alih-alih hidup dalam sesi privat. | | CLI manusia | Memberi pemelihara perintah penyiapan, penyegaran, validasi, dan inspeksi. | -| Alur kerja yang menghadap AI | Memberi agen alur kerja native host untuk sinkronisasi, dokumentasi, struktur, realisasi, dan audit. | +| Kontrak agen terpasang | Memberi agen panduan native host untuk dokumentasi, realisasi, audit, sinkronisasi akhir, dan perbaikan perutean terbatas. | | Perutean eksplisit | Memetakan area kode ke dokumen kebenaran kanonis. | | Serah terima yang dapat ditinjau | Menghasilkan diff Git biasa untuk kode maupun dokumen kebenaran. | | Operasi lokal terlebih dahulu | Tidak membutuhkan layanan ter-host, daemon, basis data, atau server MCP. | @@ -174,7 +185,7 @@ Jalur Truthmark sengaja dirancang sempit: ```text make repository truth explicit route it to code -install agent workflows around it +memasang panduan agen di sekelilingnya keep the result reviewable in Git ``` @@ -189,7 +200,7 @@ Untuk penggunaan per perintah, perbandingan permukaan, detail platform yang didu Rilis saat ini menyediakan: - perintah CLI lokal untuk config, init, check, index, impact, dan status alur kerja -- permukaan alur kerja AI yang dihasilkan untuk Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor +- instruksi agen lokal repositori yang dihasilkan untuk Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor - diagnostik perutean, otoritas, frontmatter, tautan, kesegaran, permukaan yang dihasilkan, cakupan branch, dan coverage - dokumen kebenaran berlingkup branch dan artefak kecerdasan repositori turunan diff --git a/docs/readmes/README.it.md b/docs/readmes/README.it.md index 1741a3d..9218323 100644 --- a/docs/readmes/README.it.md +++ b/docs/readmes/README.it.md @@ -69,7 +69,7 @@ Truthmark non è semplicemente un altro strumento di documentazione. È profonda * **🚫 Nessun lock-in del fornitore:** nessun servizio ospitato, nessun database nascosto, nessun server aggiuntivo da gestire. * **🌳 100% nativo di Git:** tutto vive nel tuo repository. La verità si muove con il tuo branch. -* **🤝 Architettura a due superfici:** separa nettamente gli strumenti che le persone usano per gestire il repository dai workflow che gli agenti IA usano per scrivere codice. +* **🤝 Contratto posseduto dagli umani e seguito dagli agenti:** I maintainer possiedono il contratto del repository; gli agenti seguono le istruzioni installate mentre scrivono codice. * **✅ Fiducia tramite verifica:** il lavoro dell’IA diventa più facile da fidare perché il lavoro che cambia comportamento include una decisione o un diff di documento di verità revisionabile da una persona. ## 🔄 Come funziona @@ -78,27 +78,40 @@ Quando un agente IA modifica il tuo codice, il lavoro non è finito. Truthmark i 1. 💻 **Codice:** l’agente modifica codice funzionale. 2. 🧪 **Test:** vengono eseguiti i test pertinenti. -3. 🔍 **Controllo:** `Truth Sync` controlla la documentazione mappata quando viene eseguito il workflow installato. +3. 🔍 **Controllo:** Truthmark controlla la documentazione mappata come parte della revisione finale installata. 4. 📝 **Documentazione:** i docs vengono aggiornati dall’agente quando la verità del repository è cambiata. 5. 👀 **Revisione:** una persona revisiona il *diff di codice* + il *diff di verità*. -## 🛠 Due superfici, un unico sistema di verità +## 🛠 Come interagisci con Truthmark -Truthmark è intenzionalmente diviso in due superfici distinte per servire sia i maintainer umani sia gli agenti IA. +Truthmark ha un contratto locale al repository e due modi per usarlo. -### 1. 🧑‍💻 La CLI umana (maintainer e CI) -Usata dagli sviluppatori per impostare, configurare e validare il repository. -* `truthmark config` - crea la tua configurazione iniziale. -* `truthmark init` - installa il routing, gli scaffold e le istruzioni necessari. -* `truthmark check` - valida gli artefatti di verità dal terminale. +### Gli esseri umani installano e validano il contratto -### 2. 🤖 I workflow rivolti all’IA (agenti) -Truthmark installa skills, prompt e comandi nativi che gli host IA supportati (come Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor) comprendono. Questi *non* sono comandi shell; sono punti di ingresso di workflow per l’IA. -* `/truthmark-sync` - il workflow di chiusura che gli agenti seguono dopo modifiche di codice funzionale; non è un normale comando avviato dall’utente. -* `/truthmark-document` - genera docs per codice esistente non documentato. -* `/truthmark-structure` - organizza ampie aree del repository in domini specifici. -* `/truthmark-realize` - **Sviluppo doc-first:** legge documenti di architettura e genera codice coerente. -* `/truthmark-check` - audit della verità del repository guidato dall’agente. +Maintainer e CI usano la CLI: + +* `truthmark config` - crea la configurazione iniziale. +* `truthmark init` - installa o aggiorna routing, scaffold dei documenti di verità e istruzioni per host IA. +* `truthmark check` - valida la verità del repository dal terminale. + +### Gli agenti seguono il contratto mentre scrivono codice + +Truthmark installa istruzioni locali al repository per host di coding IA supportati come Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor. + +Il ciclo normale è semplice: + +1. Chiedi al tuo agente una modifica al codice o di documentare un comportamento esistente. +2. Le istruzioni installate dicono all’agente quando testare, quando aggiornare i documenti di verità e quando fermarsi per la revisione umana. +3. Tu revisioni normali diff Git: codice più eventuali modifiche ai documenti di verità. + +Le richieste agente avviate dall’utente sono intenzionalmente poche: + +* `/truthmark-document` - documenta comportamento implementato esistente da codice e test. +* `/truthmark-realize` - implementa codice da documenti di verità esistenti. +* `/truthmark-check` - audita la verità del repository. + +Truth Sync non è il modo abituale per iniziare il lavoro; è la revisione finale dopo modifiche funzionali al codice. +Truth Structure non è un comando quotidiano; ripara routing o ownership solo quando ciò blocca il lavoro. ## Cosa ottieni @@ -107,7 +120,7 @@ Truthmark installa skills, prompt e comandi nativi che gli host IA supportati (c | Verità nativa di Git | Mantiene la verità del repository in Markdown e configurazione committati. | | Documentazione con ambito di branch | La verità si muove con il branch invece di vivere in una sessione privata. | | CLI umana | Offre ai maintainer comandi di setup, aggiornamento, validazione e ispezione. | -| Workflow rivolti all’IA | Offre agli agenti workflow nativi dell’host per sincronizzazione, documentazione, struttura, realizzazione e audit. | +| Guida agente installata | Dice agli agenti di coding quando documentare, testare, sincronizzare la verità, auditare o fermarsi per revisione. | | Routing esplicito | Mappa aree di codice a documenti di verità canonici. | | Consegne revisionabili | Produce normali diff Git sia per il codice sia per i documenti di verità. | | Operatività local-first | Non richiede servizi ospitati, daemon, database o server MCP. | @@ -150,7 +163,7 @@ Truthmark aiuta i team a rispondere con file committati, routing esplicito e dif - ownership esplicita tra docs e codice - confini di scrittura degli agenti più sicuri - documentazione revisionabile invece di memoria nascosta -- workflow IA che continuano a funzionare da file committati del repository +- guida agente che funziona ancora da file committati nel repository ## Dove si colloca Truthmark @@ -172,7 +185,7 @@ La corsia di Truthmark è stretta per progettazione: ```text make repository truth explicit route it to code -install agent workflows around it +installare guida agente intorno a essa keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ Per l’uso comando per comando, confronti tra superfici, dettagli sulle piattaf La release attuale fornisce: - comandi CLI locali per config, init, check, index, impact e stato dei workflow -- superfici di workflow IA generate per Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor +- istruzioni agente locali al repository generate per Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor - diagnostica su routing, autorità, frontmatter, link, freschezza, superfici generate, ambito di branch e copertura - documenti di verità con ambito di branch e artefatti derivati di intelligence del repository diff --git a/docs/readmes/README.ja.md b/docs/readmes/README.ja.md index 87bd237..51fd7c3 100644 --- a/docs/readmes/README.ja.md +++ b/docs/readmes/README.ja.md @@ -69,7 +69,7 @@ Truthmark は単なる別のドキュメントツールではありません。A * **🚫 ベンダーロックインなし：** ホステッドサービスも、隠れたデータベースも、運用すべき追加サーバーもありません。 * **🌳 100% Git ネイティブ：** すべてがリポジトリ内にあります。truth はブランチと一緒に移動します。 -* **🤝 デュアルサーフェスアーキテクチャ：** 人間がリポジトリ管理に使うツールと、AI エージェントがコードを書くために使うワークフローを明確に分離します。 +* **🤝 人間が所有し、エージェントが従う契約:** メンテナーがリポジトリ契約を所有し、エージェントはコーディング中にインストール済み指示に従います。 * **✅ 検証による信頼：** 振る舞いを変える作業には、人間がレビューできる truth-doc の判断または diff が含まれるため、AI の作業を信頼しやすくなります。 ## 🔄 仕組み @@ -78,27 +78,40 @@ AI エージェントがコードを変更しても、仕事はまだ終わり 1. 💻 **コード：** エージェントが機能コードを変更します。 2. 🧪 **テスト：** 関連テストを実行します。 -3. 🔍 **チェック：** インストール済みワークフローの実行時に、`Truth Sync` がマッピング済みドキュメントを確認します。 +3. 🔍 **チェック:** Truthmark は、インストール済みの終了時レビューの一部として、対応するドキュメントを確認します。 4. 📝 **ドキュメント化：** リポジトリの truth が変わった場合、エージェントがドキュメントを更新します。 5. 👀 **レビュー：** 人間が*コード diff* + *truth diff*をレビューします。 -## 🛠 2 つのサーフェス、1 つの truth システム +## 🛠 Truthmark との関わり方 -Truthmark は、人間のメンテナーと AI エージェントの両方に役立つよう、意図的に 2 つの異なるサーフェスへ分割されています。 +Truthmark には、リポジトリローカルな契約が 1 つあり、それを使う方法が 2 つあります。 + +### 人間が契約をインストールして検証する + +メンテナーと CI は CLI を使います: -### 1. 🧑‍💻 人間向け CLI（メンテナーと CI） -開発者がリポジトリをセットアップ、設定、検証するために使います。 * `truthmark config` - 初期設定を作成します。 -* `truthmark init` - 必要なルーティング、足場、指示をインストールします。 -* `truthmark check` - ターミナルから truth 成果物を検証します。 +* `truthmark init` - ルーティング、truth-doc の足場、AI ホスト向け指示をインストールまたは更新します。 +* `truthmark check` - ターミナルからリポジトリ truth を検証します。 -### 2. 🤖 AI 向けワークフロー（エージェント） -Truthmark は、Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor などの対応 AI ホストが理解できるネイティブなスキル、プロンプト、コマンドをインストールします。これらは shell コマンドでは*ありません*。AI のためのワークフロー入口です。 -* `/truthmark-sync` - 機能コード変更後にエージェントが従う完了時ワークフロー。通常のユーザー開始コマンドではありません。 -* `/truthmark-document` - ドキュメント化されていない既存コードのドキュメントを生成します。 -* `/truthmark-structure` - 広いリポジトリ領域を具体的なドメインへ整理します。 -* `/truthmark-realize` - **ドキュメントファースト開発：** アーキテクチャ文書を読み、それに一致するコードを生成します。 -* `/truthmark-check` - エージェント主導でリポジトリの truth を監査します。 +### エージェントはコーディング中に契約に従う + +Truthmark は、Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor などの対応 AI コーディングホスト向けに、リポジトリローカルな指示をインストールします。 + +通常の流れは単純です: + +1. エージェントにコード変更を依頼するか、既存の振る舞いの文書化を依頼します。 +2. インストール済みの指示が、いつテストし、いつ truth docs を更新し、いつ人間レビューのために止まるかをエージェントに伝えます。 +3. あなたは通常の Git diff をレビューします。コードと、必要なら truth-doc の変更です。 + +ユーザーが開始するエージェント依頼は意図的に少なくしています: + +* `/truthmark-document` - コードとテストから既存の実装済み振る舞いを文書化します。 +* `/truthmark-realize` - 既存の truth docs からコードを実装します。 +* `/truthmark-check` - リポジトリ truth を監査します。 + +Truth Sync は作業を始める通常の方法ではありません。機能コード変更後の終了時レビューです。 +Truth Structure は日常コマンドではありません。作業をブロックしている場合にだけ、ルーティングや所有者情報を修復します。 ## 得られるもの @@ -107,7 +120,7 @@ Truthmark は、Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、 | Git ネイティブな truth | リポジトリの truth をコミット済み Markdown と設定に保持します。 | | ブランチ単位のドキュメント | truth はプライベートセッションではなく、ブランチと一緒に移動します。 | | 人間向け CLI | メンテナーにセットアップ、更新、検証、確認のコマンドを提供します。 | -| AI 向けワークフロー | エージェントに、同期、ドキュメント化、構造化、実現、監査のためのホストネイティブなワークフローを提供します。 | +| インストール済みエージェント契約 | ドキュメント化、実現、監査、終了時 sync、限定的なルーティング修復のためのホストネイティブなガイダンスをエージェントに提供します。 | | 明示的なルーティング | コード領域を正規の truth ドキュメントに対応付けます。 | | レビュー可能な引き渡し | コードと truth ドキュメントの両方について通常の Git diff を生成します。 | | ローカルファースト運用 | ホステッドサービス、デーモン、データベース、MCP サーバーを必要としません。 | @@ -172,7 +185,7 @@ Truthmark のレーンは意図的に狭く設計されています： ```text make repository truth explicit route it to code -install agent workflows around it +その周囲にエージェント指示をインストールする keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ README は店頭のようなものです。素早い文脈、クイックスタ 現在のリリースは次を提供します： - config、init、check、index、impact、workflow status のためのローカル CLI コマンド -- Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor 向けに生成される AI ワークフローサーフェス +- Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor 向けに生成されるリポジトリローカルなエージェント指示 - ルーティング、権限、frontmatter、リンク、鮮度、生成サーフェス、ブランチスコープ、カバレッジの診断 - ブランチ単位の truth ドキュメントと、派生したリポジトリインテリジェンス成果物 diff --git a/docs/readmes/README.ko.md b/docs/readmes/README.ko.md index d693c80..ace7e60 100644 --- a/docs/readmes/README.ko.md +++ b/docs/readmes/README.ko.md @@ -69,7 +69,7 @@ Truthmark는 단순한 또 하나의 문서화 도구가 아닙니다. AI 워크 * **🚫 벤더 종속 없음:** 호스팅 서비스, 숨겨진 데이터베이스, 운영해야 할 추가 서버가 없습니다. * **🌳 100% Git 네이티브:** 모든 것이 저장소 안에 있습니다. truth는 브랜치와 함께 이동합니다. -* **🤝 이중 표면 아키텍처:** 사람이 저장소를 관리하는 데 쓰는 도구와 AI 에이전트가 코드를 작성하는 데 쓰는 워크플로를 명확히 분리합니다. +* **🤝 사람이 소유하고 에이전트가 따르는 계약:** 유지관리자가 저장소 계약을 소유하고, 에이전트는 코딩 중 설치된 지침을 따릅니다. * **✅ 검증을 통한 신뢰:** 동작을 바꾸는 작업에는 사람이 검토할 수 있는 truth-doc 결정 또는 diff가 포함되므로 AI 작업을 더 쉽게 신뢰할 수 있습니다. ## 🔄 작동 방식 @@ -78,27 +78,40 @@ AI 에이전트가 코드를 수정해도 작업은 끝난 것이 아닙니다. 1. 💻 **코드:** 에이전트가 기능 코드를 수정합니다. 2. 🧪 **테스트:** 관련 테스트가 실행됩니다. -3. 🔍 **확인:** 설치된 워크플로가 실행될 때 `Truth Sync`가 매핑된 문서를 확인합니다. +3. 🔍 **확인:** Truthmark는 설치된 마무리 검토의 일부로 매핑된 문서를 확인합니다. 4. 📝 **문서화:** 저장소 truth가 변경되면 에이전트가 문서를 업데이트합니다. 5. 👀 **검토:** 사람이 *코드 diff* + *truth diff*를 검토합니다. -## 🛠 두 표면, 하나의 truth 시스템 +## 🛠 Truthmark와 상호작용하는 방식 -Truthmark는 사람 유지관리자와 AI 에이전트 모두를 지원하기 위해 의도적으로 두 가지 별도 표면으로 나뉩니다. +Truthmark에는 저장소 로컬 계약 하나와 그것을 사용하는 두 가지 방식이 있습니다. + +### 사람은 계약을 설치하고 검증합니다 + +유지관리자와 CI는 CLI를 사용합니다: -### 1. 🧑‍💻 사람용 CLI(유지관리자 및 CI) -개발자가 저장소를 설정, 구성, 검증하는 데 사용합니다. * `truthmark config` - 초기 설정을 만듭니다. -* `truthmark init` - 필요한 라우팅, 스캐폴드, 지침을 설치합니다. -* `truthmark check` - 터미널에서 truth 산출물을 검증합니다. +* `truthmark init` - 라우팅, truth-doc 스캐폴드, AI 호스트 지침을 설치하거나 새로 고칩니다. +* `truthmark check` - 터미널에서 저장소 truth를 검증합니다. -### 2. 🤖 AI용 워크플로(에이전트) -Truthmark는 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor 같은 지원 AI 호스트가 이해하는 네이티브 스킬, 프롬프트, 명령을 설치합니다. 이것들은 shell 명령이 *아니라*, AI를 위한 워크플로 진입점입니다. -* `/truthmark-sync` - 기능 코드 변경 후 에이전트가 따르는 완료 시점 워크플로입니다. 일반적인 사용자 시작 명령이 아닙니다. -* `/truthmark-document` - 문서화되지 않은 기존 코드에 대한 문서를 생성합니다. -* `/truthmark-structure` - 넓은 저장소 영역을 구체적인 도메인으로 조직합니다. -* `/truthmark-realize` - **문서 우선 개발:** 아키텍처 문서를 읽고 그에 맞는 코드를 생성합니다. -* `/truthmark-check` - 에이전트가 주도하는 저장소 truth 감사입니다. +### 에이전트는 코딩하는 동안 계약을 따릅니다 + +Truthmark는 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor 같은 지원 AI 코딩 호스트를 위해 저장소 로컬 지침을 설치합니다. + +일반적인 루프는 단순합니다: + +1. 에이전트에게 코드 변경을 요청하거나 기존 동작을 문서화해 달라고 요청합니다. +2. 설치된 지침은 에이전트에게 언제 테스트하고, 언제 truth docs를 업데이트하고, 언제 사람 검토를 위해 멈출지 알려 줍니다. +3. 당신은 일반 Git diff를 검토합니다. 코드와 필요한 truth-doc 변경입니다. + +사용자가 시작하는 에이전트 요청은 의도적으로 적습니다: + +* `/truthmark-document` - 코드와 테스트에서 기존 구현 동작을 문서화합니다. +* `/truthmark-realize` - 기존 truth docs에서 코드를 구현합니다. +* `/truthmark-check` - 저장소 truth를 감사합니다. + +Truth Sync는 작업을 시작하는 일반적인 방법이 아니라, 기능 코드 변경 후의 마무리 검토입니다. +Truth Structure는 일상 명령이 아니라, 작업을 막는 경우에만 라우팅이나 소유권을 복구합니다. ## 얻는 것 @@ -107,7 +120,7 @@ Truthmark는 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor | Git 네이티브 truth | 저장소 truth를 커밋된 Markdown과 설정에 보관합니다. | | 브랜치 범위 문서화 | truth는 비공개 세션에 머무르지 않고 브랜치와 함께 이동합니다. | | 사람용 CLI | 유지관리자에게 설정, 새로고침, 검증, 검사 명령을 제공합니다. | -| AI용 워크플로 | 에이전트에게 동기화, 문서화, 구조화, 실현, 감사를 위한 호스트 네이티브 워크플로를 제공합니다. | +| 설치된 에이전트 지침 | 코딩 에이전트에게 언제 문서화, 테스트, truth 동기화, 감사, 검토 중지를 할지 알려 줍니다. | | 명시적 라우팅 | 코드 영역을 정식 truth 문서에 매핑합니다. | | 검토 가능한 인계 | 코드와 truth 문서 모두에 대해 일반 Git diff를 생성합니다. | | 로컬 우선 운영 | 호스팅 서비스, 데몬, 데이터베이스, MCP 서버가 필요 없습니다. | @@ -150,7 +163,7 @@ Truthmark는 커밋된 파일, 명시적 라우팅, 검토 가능한 diff로 팀 - 문서와 코드 사이의 명시적 소유권 - 더 안전한 에이전트 쓰기 경계 - 숨겨진 메모리가 아닌 검토 가능한 문서 -- 커밋된 저장소 파일에서 계속 작동하는 AI 워크플로 +- 커밋된 저장소 파일에서 계속 작동하는 에이전트 지침 ## Truthmark가 들어맞는 곳 @@ -172,7 +185,7 @@ Truthmark의 영역은 의도적으로 좁게 설계되었습니다: ```text make repository truth explicit route it to code -install agent workflows around it +그 주위에 에이전트 지침을 설치하기 keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ README는 쇼윈도입니다. 빠른 맥락, 빠른 시작, 핵심 사고 모델 현재 릴리스는 다음을 제공합니다: - config, init, check, index, impact, workflow status를 위한 로컬 CLI 명령 -- Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor용 생성 AI 워크플로 표면 +- Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor용으로 생성된 저장소 로컬 에이전트 지침 - 라우팅, 권한, frontmatter, 링크, 신선도, 생성 표면, 브랜치 범위, 커버리지 진단 - 브랜치 범위 truth 문서와 파생된 저장소 인텔리전스 산출물 diff --git a/docs/readmes/README.pl.md b/docs/readmes/README.pl.md index 3456ca5..1af5f48 100644 --- a/docs/readmes/README.pl.md +++ b/docs/readmes/README.pl.md @@ -69,7 +69,7 @@ Truthmark nie jest tylko kolejnym narzędziem do dokumentacji. Jest głęboko zi * **🚫 Zero zależności od dostawcy:** brak usług hostowanych, ukrytych baz danych i dodatkowych serwerów do utrzymywania. * **🌳 100% natywny dla Git:** wszystko mieszka w Twoim repozytorium. Truth porusza się razem z gałęzią. -* **🤝 Architektura dwóch powierzchni:** wyraźnie oddziela narzędzia używane przez ludzi do zarządzania repozytorium od workflow, których agenci AI używają do pisania kodu. +* **🤝 Kontrakt należący do ludzi i wykonywany przez agentów:** Opiekunowie posiadają kontrakt repozytorium; agenci podczas kodowania podążają za zainstalowanymi instrukcjami. * **✅ Zaufanie przez weryfikację:** pracy AI łatwiej zaufać, ponieważ zmiany wpływające na zachowanie zawierają decyzję lub diff truth-doc możliwy do przeglądu przez człowieka. ## 🔄 Jak to działa @@ -78,27 +78,40 @@ Gdy agent AI modyfikuje Twój kod, praca nie jest skończona. Truthmark instaluj 1. 💻 **Kod:** agent modyfikuje kod funkcjonalny. 2. 🧪 **Test:** wykonywane są odpowiednie testy. -3. 🔍 **Sprawdzenie:** `Truth Sync` sprawdza zmapowaną dokumentację, gdy działa zainstalowany workflow. +3. 🔍 **Sprawdzenie:** Truthmark sprawdza zmapowaną dokumentację jako część zainstalowanego końcowego przeglądu. 4. 📝 **Dokumentacja:** agent aktualizuje dokumenty, gdy truth repozytorium się zmieniła. 5. 👀 **Przegląd:** człowiek przegląda *diff kodu* + *diff truth*. -## 🛠 Dwie powierzchnie, jeden system truth +## 🛠 Jak używasz Truthmark -Truthmark jest celowo podzielony na dwie odrębne powierzchnie, aby służyć zarówno ludzkim opiekunom, jak i agentom AI. +Truthmark ma jeden lokalny kontrakt repozytorium i dwa sposoby korzystania z niego. -### 1. 🧑‍💻 CLI dla ludzi (opiekunowie i CI) -Używane przez programistów do przygotowania, konfiguracji i walidacji repozytorium. -* `truthmark config` - Tworzy początkową konfigurację. -* `truthmark init` - Instaluje potrzebny routing, szkielety i instrukcje. -* `truthmark check` - Waliduje artefakty truth z terminala. +### Ludzie instalują i walidują kontrakt -### 2. 🤖 Workflow dla AI (agenci) -Truthmark instaluje natywne umiejętności, prompty i komendy rozumiane przez obsługiwane hosty AI, takie jak Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor. To *nie* są polecenia shell; to punkty wejścia workflow dla AI. -* `/truthmark-sync` - Workflow końcowy, którego agenci przestrzegają po zmianach kodu funkcjonalnego; nie jest zwykłą komendą startową dla użytkownika. -* `/truthmark-document` - Generuje dokumenty dla istniejącego kodu bez dokumentacji. -* `/truthmark-structure` - Organizuje szerokie obszary repozytorium w konkretne domeny. -* `/truthmark-realize` - **Rozwój doc-first:** czyta dokumenty architektury i generuje kod zgodny z nimi. -* `/truthmark-check` - Audyt truth repozytorium prowadzony przez agenta. +Opiekunowie i CI używają CLI: + +* `truthmark config` - tworzy początkową konfigurację. +* `truthmark init` - instaluje lub odświeża routing, szkielety truth-doc i instrukcje dla hostów AI. +* `truthmark check` - waliduje truth repozytorium z terminala. + +### Agenci podążają za kontraktem podczas kodowania + +Truthmark instaluje lokalne instrukcje repozytorium dla obsługiwanych hostów kodowania AI, takich jak Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor. + +Normalna pętla jest prosta: + +1. Poproś agenta o zmianę kodu albo o udokumentowanie istniejącego zachowania. +2. Zainstalowane instrukcje mówią agentowi, kiedy testować, kiedy aktualizować truth docs i kiedy zatrzymać się do ludzkiego przeglądu. +3. Przeglądasz zwykłe diffy Git: kod plus ewentualne zmiany w truth-doc. + +Żądania agenta uruchamiane przez użytkownika są celowo nieliczne: + +* `/truthmark-document` - dokumentuje istniejące zaimplementowane zachowanie z kodu i testów. +* `/truthmark-realize` - implementuje kod z istniejących truth docs. +* `/truthmark-check` - audytuje truth repozytorium. + +Truth Sync nie jest zwykłym sposobem rozpoczynania pracy; to końcowy przegląd po funkcjonalnych zmianach kodu. +Truth Structure nie jest codzienną komendą; naprawia routing lub własność tylko wtedy, gdy blokuje to pracę. ## Co otrzymujesz @@ -107,7 +120,7 @@ Truthmark instaluje natywne umiejętności, prompty i komendy rozumiane przez ob | Truth natywny dla Git | Utrzymuje truth repozytorium w zatwierdzonych plikach Markdown i konfiguracji. | | Dokumentacja w zakresie gałęzi | Truth porusza się z gałęzią zamiast mieszkać w prywatnej sesji. | | CLI dla ludzi | Daje opiekunom komendy konfiguracji, odświeżania, walidacji i inspekcji. | -| Workflow dla AI | Daje agentom host-native workflow do synchronizacji, dokumentacji, strukturyzacji, realizacji i audytu. | +| Zainstalowana instrukcja agenta | Mówi agentom kodującym, kiedy dokumentować, testować, synchronizować truth, audytować lub zatrzymać się do przeglądu. | | Jawny routing | Mapuje obszary kodu na kanoniczne dokumenty truth. | | Przekazania możliwe do przeglądu | Tworzy zwykłe diffy Git zarówno dla kodu, jak i dokumentów truth. | | Działanie local-first | Nie wymaga hostowanej usługi, demona, bazy danych ani serwera MCP. | @@ -150,7 +163,7 @@ Jest przydatny, gdy potrzebujesz: - jawnej własności między dokumentami a kodem - bezpieczniejszych granic zapisu dla agentów - dokumentacji możliwej do przeglądu zamiast ukrytej pamięci -- workflow AI, które nadal działają z zatwierdzonych plików repozytorium +- instrukcje agenta, które nadal działają z commitowanych plików repozytorium ## Gdzie pasuje Truthmark @@ -172,7 +185,7 @@ Zakres Truthmark jest celowo wąski: ```text make repository truth explicit route it to code -install agent workflows around it +zainstalować wokół niej instrukcje agenta keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ Aby poznać użycie komenda po komendzie, porównanie powierzchni, szczegóły o Obecne wydanie zapewnia: - lokalne komendy CLI dla config, init, check, index, impact i workflow status -- wygenerowane powierzchnie workflow AI dla Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor +- wygenerowane lokalne instrukcje agenta dla Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor - diagnostykę route, authority, frontmatter, link, freshness, generated-surface, branch-scope i coverage - dokumenty truth w zakresie gałęzi oraz pochodne artefakty inteligencji repozytorium diff --git a/docs/readmes/README.pt.md b/docs/readmes/README.pt.md index 2313841..602054d 100644 --- a/docs/readmes/README.pt.md +++ b/docs/readmes/README.pt.md @@ -29,7 +29,7 @@ truthmark: enabled: false ``` -Em seguida, instale os documentos de verdade locais do repositório, o roteamento e as superfícies de workflow para agentes: +Em seguida, instale os documentos de verdade locais do repositório, o roteamento e as instruções para hosts de IA: ```bash truthmark init @@ -69,7 +69,7 @@ Truthmark não é apenas mais uma ferramenta de documentação. Ele é profundam * **🚫 Sem dependência de fornecedor:** nenhum serviço hospedado, nenhum banco de dados oculto, nenhum servidor extra para operar. * **🌳 100% nativo do Git:** tudo vive no seu repositório. A verdade se move com a sua branch. -* **🤝 Arquitetura de duas superfícies:** separa claramente as ferramentas que humanos usam para gerenciar o repositório dos workflows que agentes de IA usam para escrever código. +* **🤝 Contrato pertencente a humanos e seguido por agentes:** Mantenedores possuem o contrato do repositório; agentes seguem as instruções instaladas enquanto programam. * **✅ Confiança por verificação:** o trabalho da IA fica mais fácil de confiar porque trabalhos que mudam comportamento incluem uma decisão ou diff de documento de verdade revisável por humanos. ## 🔄 Como funciona @@ -78,27 +78,40 @@ Quando um agente de IA modifica seu código, o trabalho não está terminado. O 1. 💻 **Código:** o agente modifica código funcional. 2. 🧪 **Teste:** testes relevantes são executados. -3. 🔍 **Verificação:** `Truth Sync` verifica a documentação mapeada quando o workflow instalado é executado. +3. 🔍 **Verificar:** Truthmark verifica a documentação mapeada como parte da revisão de encerramento instalada. 4. 📝 **Documentação:** os docs são atualizados pelo agente quando a verdade do repositório mudou. 5. 👀 **Revisão:** uma pessoa revisa o *diff de código* + o *diff de verdade*. -## 🛠 Duas superfícies, um sistema de verdade +## 🛠 Como você interage com o Truthmark -Truthmark é intencionalmente dividido em duas superfícies distintas para atender tanto mantenedores humanos quanto agentes de IA. +Truthmark tem um contrato local do repositório e duas formas de usá-lo. -### 1. 🧑‍💻 A CLI humana (mantenedores e CI) -Usada por desenvolvedores para preparar, configurar e validar o repositório. -* `truthmark config` - cria sua configuração inicial. -* `truthmark init` - instala o roteamento, os scaffolds e as instruções necessários. -* `truthmark check` - valida artefatos de verdade a partir do terminal. +### Pessoas instalam e validam o contrato -### 2. 🤖 Os workflows voltados para IA (agentes) -Truthmark instala skills, prompts e comandos nativos que hosts de IA compatíveis (como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor) entendem. Eles *não* são comandos de shell; são pontos de entrada de workflow para a IA. -* `/truthmark-sync` - o workflow de encerramento que os agentes seguem após mudanças em código funcional; não é um comando comum iniciado pelo usuário. -* `/truthmark-document` - gera docs para código existente sem documentação. -* `/truthmark-structure` - organiza áreas amplas do repositório em domínios específicos. -* `/truthmark-realize` - **Desenvolvimento doc-first:** lê documentos de arquitetura e gera código correspondente. -* `/truthmark-check` - auditoria da verdade do repositório conduzida pelo agente. +Mantenedores e CI usam a CLI: + +* `truthmark config` - cria a configuração inicial. +* `truthmark init` - instala ou atualiza roteamento, scaffolds de documentos de verdade e instruções para hosts de IA. +* `truthmark check` - valida a verdade do repositório pelo terminal. + +### Agentes seguem o contrato enquanto programam + +Truthmark instala instruções locais do repositório para hosts de codificação com IA compatíveis, como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor. + +O ciclo normal é simples: + +1. Peça ao seu agente uma mudança de código ou que documente um comportamento existente. +2. As instruções instaladas dizem ao agente quando testar, quando atualizar documentos de verdade e quando parar para revisão humana. +3. Você revisa diffs Git comuns: código mais quaisquer mudanças em documentos de verdade. + +As solicitações de agente iniciadas pelo usuário são intencionalmente poucas: + +* `/truthmark-document` - documenta comportamento implementado existente a partir de código e testes. +* `/truthmark-realize` - implementa código a partir de documentos de verdade existentes. +* `/truthmark-check` - audita a verdade do repositório. + +Truth Sync não é o modo usual de começar trabalho; é a revisão de encerramento após mudanças funcionais de código. +Truth Structure não é um comando cotidiano; ele repara roteamento ou propriedade somente quando isso bloqueia o trabalho. ## O que você recebe @@ -107,7 +120,7 @@ Truthmark instala skills, prompts e comandos nativos que hosts de IA compatívei | Verdade nativa do Git | Mantém a verdade do repositório em Markdown e configuração commitados. | | Documentação com escopo de branch | A verdade se move com a branch em vez de viver em uma sessão privada. | | CLI humana | Dá aos mantenedores comandos de configuração, atualização, validação e inspeção. | -| Workflows voltados para IA | Dá aos agentes workflows nativos do host para sincronização, documentação, estrutura, realização e auditoria. | +| Orientação de agente instalada | Diz aos agentes de codificação quando documentar, testar, sincronizar verdade, auditar ou parar para revisão. | | Roteamento explícito | Mapeia áreas de código para documentos de verdade canônicos. | | Entregas revisáveis | Produz diffs Git comuns tanto para código quanto para documentos de verdade. | | Operação local-first | Não requer serviço hospedado, daemon, banco de dados nem servidor MCP. | @@ -150,7 +163,7 @@ Ele é útil quando você precisa de: - ownership explícito entre docs e código - limites de escrita de agentes mais seguros - documentação revisável em vez de memória oculta -- workflows de IA que ainda funcionam a partir de arquivos commitados do repositório +- orientação de agente que ainda funciona a partir de arquivos commitados no repositório ## Onde o Truthmark se encaixa @@ -172,7 +185,7 @@ A faixa de atuação do Truthmark é estreita por design: ```text make repository truth explicit route it to code -install agent workflows around it +instalar orientação de agente ao redor dela keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ Para uso comando por comando, comparações de superfícies, detalhes de platafo A versão atual fornece: - comandos CLI locais para config, init, check, index, impact e status de workflows -- superfícies de workflow de IA geradas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor +- instruções de agente locais do repositório geradas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor - diagnósticos de roteamento, autoridade, frontmatter, links, frescor, superfícies geradas, escopo de branch e cobertura - documentos de verdade com escopo de branch e artefatos derivados de inteligência do repositório diff --git a/docs/readmes/README.ru.md b/docs/readmes/README.ru.md index ff98e5e..b5082dc 100644 --- a/docs/readmes/README.ru.md +++ b/docs/readmes/README.ru.md @@ -69,7 +69,7 @@ Truthmark — не просто очередной инструмент доку * **🚫 Никакой привязки к поставщику:** нет hosted-сервисов, скрытых баз данных и дополнительных серверов для эксплуатации. * **🌳 100% Git-native:** всё находится в вашем репозитории. Truth движется вместе с веткой. -* **🤝 Архитектура с двумя поверхностями:** она четко разделяет инструменты, которыми люди управляют репозиторием, и workflows, которыми AI-агенты пишут код. +* **🤝 Контракт, принадлежащий людям и выполняемый агентами:** Мейнтейнеры владеют контрактом репозитория; агенты следуют установленным инструкциям во время кодинга. * **✅ Доверие через проверку:** AI-работе проще доверять, потому что работа, меняющая поведение, включает human-reviewable решение или diff в truth-doc. ## 🔄 Как это работает @@ -78,27 +78,40 @@ Truthmark — не просто очередной инструмент доку 1. 💻 **Код:** агент изменяет функциональный код. 2. 🧪 **Тест:** выполняются релевантные тесты. -3. 🔍 **Проверка:** `Truth Sync` проверяет сопоставленную документацию, когда запускается установленный workflow. +3. 🔍 **Проверка:** Truthmark проверяет сопоставленную документацию как часть установленного завершающего ревью. 4. 📝 **Документирование:** агент обновляет docs, когда truth репозитория изменился. 5. 👀 **Ревью:** человек проверяет *diff кода* + *diff truth*. -## 🛠 Две поверхности, одна система truth +## 🛠 Как вы взаимодействуете с Truthmark -Truthmark намеренно разделен на две разные поверхности, чтобы обслуживать и людей-мейнтейнеров, и AI-агентов. +У Truthmark есть один локальный контракт репозитория и два способа его использовать. -### 1. 🧑‍💻 CLI для людей (мейнтейнеры и CI) -Используется разработчиками для настройки, конфигурации и проверки репозитория. -* `truthmark config` - Создает начальную конфигурацию. -* `truthmark init` - Устанавливает необходимые маршруты, scaffold и инструкции. -* `truthmark check` - Проверяет truth-артефакты из терминала. +### Люди устанавливают и проверяют контракт -### 2. 🤖 Workflows для AI (агенты) -Truthmark устанавливает native skills, prompts и commands, которые понимают поддерживаемые AI-хосты, такие как Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor. Это *не* shell-команды; это точки входа workflow для AI. -* `/truthmark-sync` - Завершающий workflow, которому агенты следуют после изменений функционального кода; не обычная команда, запускаемая пользователем. -* `/truthmark-document` - Генерирует docs для недокументированного существующего кода. -* `/truthmark-structure` - Организует широкие области репозитория в конкретные домены. -* `/truthmark-realize` - **Doc-First Development:** читает архитектурные docs и генерирует соответствующий код. -* `/truthmark-check` - Управляемый агентом аудит truth репозитория. +Мейнтейнеры и CI используют CLI: + +* `truthmark config` - создает начальную конфигурацию. +* `truthmark init` - устанавливает или обновляет маршруты, scaffold для truth-doc и инструкции для AI-хостов. +* `truthmark check` - проверяет truth репозитория из терминала. + +### Агенты следуют контракту во время кодинга + +Truthmark устанавливает локальные инструкции репозитория для поддерживаемых AI coding hosts, таких как Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor. + +Обычный цикл прост: + +1. Попросите агента изменить код или задокументировать существующее поведение. +2. Установленные инструкции говорят агенту, когда тестировать, когда обновлять truth docs и когда остановиться для человеческого ревью. +3. Вы ревьюите обычные Git diff: код плюс любые изменения truth-doc. + +Пользовательских запросов к агенту намеренно мало: + +* `/truthmark-document` - документирует существующее реализованное поведение по коду и тестам. +* `/truthmark-realize` - реализует код из существующих truth docs. +* `/truthmark-check` - аудитирует truth репозитория. + +Truth Sync — не обычный способ начать работу; это завершающее ревью после функциональных изменений кода. +Truth Structure — не повседневная команда; она исправляет routing или ownership только тогда, когда это блокирует работу. ## Что вы получаете @@ -107,7 +120,7 @@ Truthmark устанавливает native skills, prompts и commands, кот | Git-native truth | Хранит truth репозитория в закоммиченных Markdown и конфигурации. | | Документация в пределах ветки | Truth движется с веткой, а не живет в приватной сессии. | | CLI для людей | Дает мейнтейнерам команды настройки, обновления, валидации и инспекции. | -| Workflows для AI | Дает агентам host-native workflows для sync, documentation, structure, realization и audit. | +| Установленные инструкции агента | Говорит coding-агентам, когда документировать, тестировать, синхронизировать truth, аудитировать или останавливаться для ревью. | | Явная маршрутизация | Сопоставляет области кода с каноническими truth-docs. | | Проверяемая передача | Создает обычные Git diff как для кода, так и для truth-docs. | | Local-first работа | Не требует hosted-сервиса, daemon, базы данных или MCP-сервера. | @@ -119,7 +132,7 @@ Truthmark устанавливает native skills, prompts и commands, кот ![Возможности Truthmark](../assets/truthmark-features.png) -**Возможности:** что устанавливает Truthmark и как разделена workflow surface. +**Возможности:** что устанавливает Truthmark и как агенты используют локальные инструкции репозитория. ![Позиционирование Truthmark](../assets/truthmark-position.png) @@ -150,7 +163,7 @@ Truthmark помогает командам отвечать на это с по - явное владение между docs и кодом - более безопасные границы записи для агентов - проверяемая документация вместо скрытой memory -- AI workflows, которые всё еще работают из закоммиченных файлов репозитория +- инструкции для агентов, которые продолжают работать из закоммиченных файлов репозитория ## Где уместен Truthmark @@ -172,7 +185,7 @@ Truthmark не заменяет prompts, memory, specs, tests или code review ```text make repository truth explicit route it to code -install agent workflows around it +установить вокруг нее инструкции для агентов keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ README — это витрина: быстрый контекст, быстры Текущий релиз предоставляет: - локальные CLI-команды для config, init, check, index, impact и workflow status -- сгенерированные AI workflow surfaces для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor +- сгенерированные локальные инструкции агента для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor - диагностику route, authority, frontmatter, links, freshness, generated-surface, branch-scope и coverage - branch-scoped truth docs и производные артефакты repository intelligence diff --git a/docs/readmes/README.tr.md b/docs/readmes/README.tr.md index 69fc079..f4661a8 100644 --- a/docs/readmes/README.tr.md +++ b/docs/readmes/README.tr.md @@ -69,7 +69,7 @@ Truthmark sıradan bir dokümantasyon aracı değildir. AI iş akışına derinl * **🚫 Tedarikçi kilidi yok:** Barındırılan hizmet yok, gizli veritabanı yok, işletilecek ek sunucu yok. * **🌳 %100 Git'e özgü:** Her şey deponuzda yaşar. Gerçek, dalınızla birlikte hareket eder. -* **🤝 Çift yüzeyli mimari:** İnsanların depoyu yönetmek için kullandığı araçları, AI ajanlarının kod yazmak için kullandığı iş akışlarından temiz biçimde ayırır. +* **🤝 İnsanların sahip olduğu, ajanların izlediği sözleşme:** Bakımcılar depo sözleşmesine sahiptir; ajanlar kod yazarken kurulu talimatları izler. * **✅ Doğrulama yoluyla güven:** Davranışı değiştiren işlerde insan tarafından incelenebilir bir gerçeklik belgesi kararı veya farkı bulunduğu için AI çalışmasına güvenmek kolaylaşır. ## 🔄 Nasıl çalışır @@ -78,29 +78,40 @@ Bir AI ajanı kodunuzu değiştirdiğinde iş bitmiş sayılmaz. Truthmark, ajan 1. 💻 **Kod:** Ajan işlevsel kodu değiştirir. 2. 🧪 **Test:** İlgili testler çalıştırılır. -3. 🔍 **Kontrol:** Kurulu iş akışı çalıştığında `Truth Sync` eşlenmiş belgeleri kontrol eder. +3. 🔍 **Kontrol:** Truthmark, kurulu bitiş incelemesinin parçası olarak eşlenen dokümantasyonu kontrol eder. 4. 📝 **Belgeleme:** Depo gerçeği değiştiğinde belgeler ajan tarafından güncellenir. 5. 👀 **İnceleme:** Bir insan *kod farkını* + *gerçeklik farkını* inceler. -## 🛠 İki yüzey, tek gerçeklik sistemi +## 🛠 Truthmark ile nasıl etkileşirsiniz -Truthmark, hem insan bakımcılarına hem de AI ajanlarına hizmet etmek için bilinçli olarak iki ayrı yüzeye bölünmüştür. +Truthmark’ın depo yerelinde tek bir sözleşmesi ve onu kullanmanın iki yolu vardır. -### 1. 🧑‍💻 İnsan CLI'si (Bakımcılar ve CI) +### İnsanlar sözleşmeyi kurar ve doğrular -Geliştiriciler tarafından depoyu kurmak, yapılandırmak ve doğrulamak için kullanılır. -* `truthmark config` - İlk yapılandırmanızı oluşturur. -* `truthmark init` - Gerekli yönlendirmeyi, iskeletleri ve talimatları kurar. -* `truthmark check` - Gerçeklik artefaktlarını terminalden doğrular. +Bakımcılar ve CI, CLI kullanır: -### 2. 🤖 AI'ye yönelik iş akışları (Ajanlar) +* `truthmark config` - ilk yapılandırmayı oluşturur. +* `truthmark init` - yönlendirmeyi, truth-doc iskelelerini ve AI ana makine talimatlarını kurar veya yeniler. +* `truthmark check` - depo gerçeğini terminalden doğrular. -Truthmark, desteklenen AI ana makinelerinin (Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor gibi) anlayabildiği yerel beceriler, istemler ve komutlar kurar. Bunlar shell komutları *değildir*; AI için iş akışı giriş noktalarıdır. -* `/truthmark-sync` - İşlevsel kod değişikliklerinden sonra ajanların izlediği bitiş zamanı iş akışı; normal bir kullanıcı başlatma komutu değildir. -* `/truthmark-document` - Belgesiz mevcut kod için belgeler üretir. -* `/truthmark-structure` - Geniş depo alanlarını belirli alan adları halinde düzenler. -* `/truthmark-realize` - **Belge-öncelikli geliştirme:** Mimari belgelerini okur ve bunlara uyan kod üretir. -* `/truthmark-check` - Ajan tarafından yürütülen depo gerçeği denetimi. +### Ajanlar kod yazarken sözleşmeyi izler + +Truthmark, Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor gibi desteklenen AI kodlama ana makineleri için depo yerelinde talimatlar kurar. + +Normal döngü basittir: + +1. Ajanınızdan kod değişikliği isteyin veya mevcut bir davranışı belgelemesini isteyin. +2. Kurulu talimatlar ajana ne zaman test edeceğini, ne zaman truth dokümanlarını güncelleyeceğini ve ne zaman insan incelemesi için duracağını söyler. +3. Siz sıradan Git diff’lerini incelersiniz: kod ve varsa truth-doc değişiklikleri. + +Kullanıcı tarafından başlatılan ajan istekleri bilinçli olarak azdır: + +* `/truthmark-document` - kod ve testlerden mevcut uygulanmış davranışı belgeler. +* `/truthmark-realize` - mevcut truth dokümanlarından kod uygular. +* `/truthmark-check` - depo gerçeğini denetler. + +Truth Sync işe başlamanın olağan yolu değildir; işlevsel kod değişikliklerinden sonraki bitiş incelemesidir. +Truth Structure günlük bir komut değildir; yalnızca çalışmayı engellediğinde yönlendirmeyi veya sahipliği onarır. ## Neler elde edersiniz @@ -109,7 +120,7 @@ Truthmark, desteklenen AI ana makinelerinin (Codex, Claude Code, GitHub Copilot, | Git'e özgü gerçeklik | Depo gerçeğini commit edilmiş Markdown ve yapılandırmada tutar. | | Dal kapsamlı dokümantasyon | Gerçek, özel bir oturumda yaşamak yerine dalla birlikte hareket eder. | | İnsan CLI'si | Bakımcılara kurulum, yenileme, doğrulama ve inceleme komutları sağlar. | -| AI'ye yönelik iş akışları | Ajanlara senkronizasyon, dokümantasyon, yapılandırma, gerçekleştirme ve denetim için ana makineye özgü iş akışları sağlar. | +| Kurulu ajan rehberliği | Kodlama ajanlarına ne zaman belge yazacağını, test edeceğini, gerçeği senkronize edeceğini, denetleyeceğini veya inceleme için duracağını söyler. | | Açık yönlendirme | Kod alanlarını kanonik gerçeklik belgelerine eşler. | | İncelenebilir teslimler | Hem kod hem de gerçeklik belgeleri için sıradan Git farkları üretir. | | Yerel-öncelikli çalışma | Barındırılan hizmet, daemon, veritabanı veya MCP sunucusu gerektirmez. | @@ -174,7 +185,7 @@ Truthmark'ın alanı tasarım gereği dardır: ```text make repository truth explicit route it to code -install agent workflows around it +etrafına ajan rehberliği kurmak keep the result reviewable in Git ``` @@ -189,7 +200,7 @@ Komut komut kullanım, yüzey karşılaştırmaları, desteklenen platform ayrı Mevcut sürüm şunları sağlar: - config, init, check, index, impact ve iş akışı durumu için yerel CLI komutları -- Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor için üretilmiş AI iş akışı yüzeyleri +- Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor için oluşturulan depo yerelinde ajan talimatları - yönlendirme, yetki, frontmatter, bağlantı, güncellik, üretilmiş yüzey, dal kapsamı ve kapsam tanıları - dal kapsamlı gerçeklik belgeleri ve türetilmiş depo zekâsı artefaktları diff --git a/docs/readmes/README.vi.md b/docs/readmes/README.vi.md index 4813f49..fe81846 100644 --- a/docs/readmes/README.vi.md +++ b/docs/readmes/README.vi.md @@ -69,7 +69,7 @@ Truthmark không chỉ là một công cụ tài liệu khác. Nó được tíc * **🚫 Không bị khóa vào nhà cung cấp:** Không dịch vụ lưu trữ, không cơ sở dữ liệu ẩn, không máy chủ bổ sung để vận hành. * **🌳 100% gốc Git:** Mọi thứ nằm trong kho của bạn. Sự thật di chuyển cùng nhánh của bạn. -* **🤝 Kiến trúc hai bề mặt:** Tách rõ công cụ con người dùng để quản lý kho khỏi quy trình tác tử AI dùng để viết mã. +* **🤝 Hợp đồng do con người sở hữu, tác tử tuân theo:** Người bảo trì sở hữu hợp đồng kho; tác tử tuân theo hướng dẫn đã cài đặt khi viết mã. * **✅ Tin cậy qua xác minh:** Công việc AI dễ được tin tưởng hơn vì công việc thay đổi hành vi bao gồm một quyết định hoặc diff tài liệu sự thật mà con người có thể xem xét. ## 🔄 Cách hoạt động @@ -78,29 +78,40 @@ Khi một tác tử AI sửa mã của bạn, công việc chưa kết thúc. Tr 1. 💻 **Mã:** Tác tử sửa mã chức năng. 2. 🧪 **Kiểm thử:** Các kiểm thử liên quan được chạy. -3. 🔍 **Kiểm tra:** `Truth Sync` kiểm tra tài liệu đã ánh xạ khi quy trình đã cài đặt chạy. +3. 🔍 **Kiểm tra:** Truthmark kiểm tra tài liệu được ánh xạ như một phần của bước xem xét kết thúc đã cài đặt. 4. 📝 **Ghi tài liệu:** Tài liệu được tác tử cập nhật khi sự thật của kho thay đổi. 5. 👀 **Xem xét:** Con người xem xét *diff mã* + *diff sự thật*. -## 🛠 Hai bề mặt, một hệ thống sự thật +## 🛠 Cách bạn tương tác với Truthmark -Truthmark được cố ý chia thành hai bề mặt riêng biệt để phục vụ cả người bảo trì và tác tử AI. +Truthmark có một hợp đồng cục bộ trong kho và hai cách sử dụng nó. -### 1. 🧑‍💻 CLI dành cho con người (người bảo trì & CI) +### Con người cài đặt và xác thực hợp đồng -Được nhà phát triển dùng để thiết lập, cấu hình và xác thực kho. -* `truthmark config` - Tạo cấu hình ban đầu của bạn. -* `truthmark init` - Cài đặt định tuyến, khung mẫu và chỉ dẫn cần thiết. -* `truthmark check` - Xác thực các hiện vật sự thật từ terminal. +Người bảo trì và CI dùng CLI: -### 2. 🤖 Quy trình hướng tới AI (tác tử) +* `truthmark config` - tạo cấu hình ban đầu. +* `truthmark init` - cài đặt hoặc làm mới định tuyến, scaffold truth-doc và hướng dẫn cho AI host. +* `truthmark check` - xác thực sự thật của kho từ terminal. -Truthmark cài đặt các kỹ năng, prompt và lệnh gốc mà các máy chủ AI được hỗ trợ (như Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor) hiểu được. Đây *không phải* lệnh shell; chúng là điểm vào quy trình cho AI. -* `/truthmark-sync` - Quy trình lúc hoàn tất mà tác tử tuân theo sau các thay đổi mã chức năng; không phải lệnh khởi đầu thông thường cho người dùng. -* `/truthmark-document` - Tạo tài liệu cho mã hiện có chưa được ghi tài liệu. -* `/truthmark-structure` - Tổ chức các khu vực kho rộng thành các miền cụ thể. -* `/truthmark-realize` - **Phát triển theo tài liệu trước:** Đọc tài liệu kiến trúc và tạo mã cho khớp. -* `/truthmark-check` - Kiểm toán truth của kho do tác tử điều khiển. +### Tác tử tuân theo hợp đồng khi viết mã + +Truthmark cài đặt hướng dẫn cục bộ trong kho cho các AI coding host được hỗ trợ như Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor. + +Vòng lặp bình thường rất đơn giản: + +1. Yêu cầu tác tử thay đổi mã hoặc ghi tài liệu cho một hành vi hiện có. +2. Hướng dẫn đã cài đặt cho tác tử biết khi nào cần kiểm thử, khi nào cập nhật truth docs và khi nào dừng để con người xem xét. +3. Bạn xem xét các Git diff thông thường: mã cộng với mọi thay đổi truth-doc. + +Các yêu cầu tác tử do người dùng khởi động được cố ý giữ ít: + +* `/truthmark-document` - ghi tài liệu cho hành vi đã triển khai hiện có từ mã và kiểm thử. +* `/truthmark-realize` - triển khai mã từ truth docs hiện có. +* `/truthmark-check` - kiểm toán sự thật của kho. + +Truth Sync không phải cách thông thường để bắt đầu công việc; đó là bước xem xét kết thúc sau các thay đổi mã chức năng. +Truth Structure không phải lệnh hằng ngày; nó chỉ sửa định tuyến hoặc quyền sở hữu khi điều đó chặn công việc. ## Bạn nhận được gì @@ -109,7 +120,7 @@ Truthmark cài đặt các kỹ năng, prompt và lệnh gốc mà các máy ch | Sự thật gốc Git | Giữ sự thật của kho trong Markdown và cấu hình đã commit. | | Tài liệu theo phạm vi nhánh | Sự thật di chuyển cùng nhánh thay vì sống trong một phiên riêng tư. | | CLI dành cho con người | Cung cấp cho người bảo trì các lệnh thiết lập, làm mới, xác thực và kiểm tra. | -| Quy trình hướng tới AI | Cung cấp cho tác tử các quy trình gốc theo máy chủ cho đồng bộ, tài liệu, cấu trúc, hiện thực hóa và kiểm toán. | +| Hướng dẫn tác tử đã cài đặt | Cho tác tử lập trình biết khi nào ghi tài liệu, kiểm thử, đồng bộ sự thật, kiểm toán hoặc dừng để xem xét. | | Định tuyến rõ ràng | Ánh xạ các vùng mã tới tài liệu sự thật chuẩn. | | Bàn giao có thể xem xét | Tạo các diff Git thông thường cho cả mã và tài liệu sự thật. | | Vận hành ưu tiên cục bộ | Không yêu cầu dịch vụ lưu trữ, daemon, cơ sở dữ liệu hoặc máy chủ MCP. | @@ -174,7 +185,7 @@ Làn đường của Truthmark được thiết kế có chủ ý là hẹp: ```text make repository truth explicit route it to code -install agent workflows around it +cài đặt hướng dẫn tác tử quanh nó keep the result reviewable in Git ``` @@ -189,7 +200,7 @@ README là mặt tiền: ngữ cảnh nhanh, bắt đầu nhanh và mô hình t Bản phát hành hiện tại cung cấp: - các lệnh CLI cục bộ cho config, init, check, index, impact và trạng thái quy trình -- các bề mặt quy trình AI được tạo cho Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor +- hướng dẫn tác tử cục bộ trong kho được tạo cho Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor - chẩn đoán về định tuyến, thẩm quyền, frontmatter, liên kết, độ mới, bề mặt sinh ra, phạm vi nhánh và độ phủ - tài liệu sự thật theo phạm vi nhánh và các hiện vật trí tuệ kho được suy dẫn diff --git a/docs/readmes/README.zh.md b/docs/readmes/README.zh.md index 904e415..33925c9 100644 --- a/docs/readmes/README.zh.md +++ b/docs/readmes/README.zh.md @@ -29,7 +29,7 @@ truthmark: enabled: false ``` -然后安装仓库本地的事实文档、路由和代理工作流界面： +然后安装仓库本地的事实文档、路由和 AI 宿主指令： ```bash truthmark init @@ -69,7 +69,7 @@ Truthmark 不只是另一个文档工具。它深度集成到 AI 工作流中： * **🚫 零供应商锁定：** 没有托管服务、隐藏数据库，也没有需要额外运维的服务器。 * **🌳 100% Git 原生：** 一切都存在于你的仓库中。事实随分支一起移动。 -* **🤝 双界面架构：** 它清晰分离人类用于管理仓库的工具，以及 AI 代理用于编写代码的工作流。 +* **🤝 人类拥有、代理遵循的契约：**维护者拥有仓库契约；代理在编码时遵循已安装的指令。 * **✅ 通过验证建立信任：** 因为改变行为的工作会包含可由人类审查的事实文档决策或 diff，AI 工作更容易被信任。 ## 🔄 工作原理 @@ -78,27 +78,40 @@ Truthmark 不只是另一个文档工具。它深度集成到 AI 工作流中： 1. 💻 **代码：** 代理修改功能代码。 2. 🧪 **测试：** 执行相关测试。 -3. 🔍 **检查：** 已安装工作流运行时，`Truth Sync` 会检查已映射的文档。 +3. 🔍 **检查：**Truthmark 会把映射到的文档作为已安装收尾审查的一部分进行检查。 4. 📝 **记录：** 当仓库事实发生变化时，代理更新文档。 5. 👀 **审查：** 人类审查*代码 diff* + *事实 diff*。 -## 🛠 两个界面，一个事实系统 +## 🛠 你如何使用 Truthmark -Truthmark 有意拆分为两个不同界面，以同时服务人类维护者和 AI 代理。 +Truthmark 有一个仓库本地契约，以及两种使用方式。 + +### 人类安装并验证契约 + +维护者和 CI 使用 CLI： -### 1. 🧑‍💻 人类 CLI（维护者和 CI） -供开发者设置、配置和验证仓库使用。 * `truthmark config` - 创建初始配置。 -* `truthmark init` - 安装必要的路由、脚手架和指令。 -* `truthmark check` - 从终端验证事实产物。 +* `truthmark init` - 安装或刷新路由、事实文档脚手架和 AI 宿主指令。 +* `truthmark check` - 从终端验证仓库事实。 -### 2. 🤖 面向 AI 的工作流（代理） -Truthmark 会安装受支持 AI 宿主（如 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor）能够理解的原生技能、提示和命令。这些*不是* shell 命令；它们是 AI 的工作流入口点。 -* `/truthmark-sync` - 代理在功能代码变化后遵循的收尾工作流；不是普通的用户启动命令。 -* `/truthmark-document` - 为尚未记录的既有代码生成文档。 -* `/truthmark-structure` - 将宽泛的仓库区域组织为具体领域。 -* `/truthmark-realize` - **文档优先开发：** 阅读架构文档并生成与之匹配的代码。 -* `/truthmark-check` - 由代理驱动的仓库事实审计。 +### 代理在编码时遵循契约 + +Truthmark 会为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 等受支持的 AI 编码宿主安装仓库本地指令。 + +正常循环很简单： + +1. 让代理修改代码，或让它记录已有行为。 +2. 已安装的指令会告诉代理何时测试、何时更新事实文档、何时停下来交给人类审查。 +3. 你审查普通的 Git diff：代码，以及任何事实文档变更。 + +用户主动发起的代理请求刻意保持很少： + +* `/truthmark-document` - 根据代码和测试记录已有实现行为。 +* `/truthmark-realize` - 根据已有事实文档实现代码。 +* `/truthmark-check` - 审计仓库事实。 + +Truth Sync 不是通常的开工方式；它是功能代码变更后的收尾审查。 +Truth Structure 不是日常命令；只有当路由或所有权阻塞工作时，它才进行修复。 ## 你会得到什么 @@ -107,7 +120,7 @@ Truthmark 会安装受支持 AI 宿主（如 Codex、Claude Code、GitHub Copilo | Git 原生事实 | 将仓库事实保存在已提交的 Markdown 和配置中。 | | 按分支生效的文档 | 事实随分支移动，而不是存在于私有会话中。 | | 人类 CLI | 为维护者提供设置、刷新、验证和检查命令。 | -| 面向 AI 的工作流 | 为代理提供宿主原生的同步、文档、结构、实现和审计工作流。 | +| 已安装的代理指引 | 告诉编码代理何时记录文档、测试、同步事实、审计或停下来等待审查。 | | 显式路由 | 将代码区域映射到规范事实文档。 | | 可审查交接 | 为代码和事实文档都产生普通 Git diff。 | | 本地优先运行 | 不需要托管服务、守护进程、数据库或 MCP 服务器。 | @@ -119,7 +132,7 @@ Truthmark 会安装受支持 AI 宿主（如 Codex、Claude Code、GitHub Copilo ![Truthmark 功能](../assets/truthmark-features.png) -**功能：** Truthmark 会安装什么，以及工作流界面如何拆分。 +**功能：** Truthmark 会安装什么，以及代理如何使用仓库本地指令。 ![Truthmark 定位](../assets/truthmark-position.png) @@ -172,7 +185,7 @@ Truthmark 的边界有意很窄： ```text make repository truth explicit route it to code -install agent workflows around it +围绕它安装代理指引 keep the result reviewable in Git ``` @@ -187,7 +200,7 @@ README 是门面：快速背景、快速开始和核心心智模型。 当前版本提供： - 用于 config、init、check、index、impact 和 workflow status 的本地 CLI 命令 -- 为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 生成的 AI 工作流界面 +- 为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 生成的仓库本地代理指令 - 路由、权限、frontmatter、链接、新鲜度、生成界面、分支范围和覆盖率诊断 - 按分支生效的事实文档和派生的仓库智能产物