mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
Workflow Verifier And Writer Agents v1.4.0 (#5)
* feat(workflows): add verifier agent surfaces Generate project-scoped read-only verifier agents for Codex, Claude Code, GitHub Copilot, and OpenCode. Wire workflow manifests, generated surfaces, init diagnostics, sync classification, docs, and tests through the new subagent contract. * feat(workflows): add leased truth doc writer agents Add write-capable truth-doc-writer generated surfaces for Codex, Claude, Copilot, and OpenCode, guarded by explicit write leases. Tighten Truth Sync and Truth Document subagent contracts so parents validate leases, changed files, and worker reports before accepting doc updates. * feat(workflows): add Truth Preview and workflow support files Add the explicit read-only Truth Preview workflow across the manifest, generated host surfaces, docs, and tests. Move generated skill hosts to compact SKILL.md entrypoints with support procedure, report, and lease files, and add write-worker report acceptance validation against actual lease diffs.
This commit is contained in:
MerlinH
@@ -0,0 +1,19 @@
|
||||
---
|
||||
name: truth-claim-verifier
|
||||
description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence.
|
||||
tools: [read, search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Stay read-only.
|
||||
Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
|
||||
Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
|
||||
Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
|
||||
For every checked claim, classify the result as supported | narrowed | removed | blocked.
|
||||
Do not edit files, stage changes, or invent missing behavior.
|
||||
Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
name: truth-doc-reviewer
|
||||
description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene.
|
||||
tools: [read, search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Stay read-only.
|
||||
Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale.
|
||||
Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
|
||||
Do not edit files, stage changes, or rewrite docs.
|
||||
Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
|
||||
recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
name: truth-doc-writer
|
||||
description: Write-capable Truthmark doc worker for one parent-leased truth-document shard.
|
||||
tools: [read, search, edit]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Write one leased Truthmark truth-document shard assigned by the parent.
|
||||
Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields.
|
||||
Read every requiredReads entry directly before editing.
|
||||
Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
|
||||
Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
|
||||
Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
|
||||
Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
|
||||
status must be completed or blocked.
|
||||
filesChanged must list only files you actually changed.
|
||||
offLeaseChanges must be empty for completed reports.
|
||||
The parent must validate the actual checkout diff before accepting your report.
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
name: truth-route-auditor
|
||||
description: Read-only Truthmark route auditor for bounded routing and ownership verification.
|
||||
tools: [read, search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Stay read-only.
|
||||
Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
|
||||
Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly.
|
||||
Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
|
||||
Do not edit files, stage changes, or propose broad rewrites.
|
||||
Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
|
||||
recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
@@ -1,14 +1,22 @@
|
||||
Follow `docs/ai/repo-rules.md`.
|
||||
|
||||
Use that file as the primary repository instruction source for this agent.
|
||||
|
||||
Agent-specific:
|
||||
- Read `docs/README.md` only when choosing or updating canonical docs.
|
||||
- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.
|
||||
|
||||
<!-- truthmark:start -->
|
||||
## Truthmark Workflow
|
||||
|
||||
Generated by Truthmark 1.3.0. Rerun `truthmark init` after upgrades.
|
||||
Generated by Truthmark 1.4.0. Rerun `truthmark init` after upgrades.
|
||||
Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md.
|
||||
Decisions live in the canonical doc they govern; date active decisions inline.
|
||||
Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned.
|
||||
### Truth Sync
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
@@ -8,7 +8,7 @@ name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
@@ -36,6 +36,13 @@ Evidence Gate:
|
||||
- canonical docs are context, not sole proof when implementation conflicts
|
||||
- remove unsupported findings or mark open questions; validate changed claims if you edit docs
|
||||
|
||||
Copilot custom-agent mode:
|
||||
- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
|
||||
- dispatch read-only project custom agents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer
|
||||
- custom agents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Check report
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
|
||||
@@ -8,7 +8,7 @@ name: truthmark-document
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
@@ -50,6 +50,16 @@ Evidence Gate:
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or block unsupported claims
|
||||
- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked
|
||||
Copilot custom-agent mode:
|
||||
- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
|
||||
- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier
|
||||
- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer
|
||||
- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
|
||||
- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
|
||||
- parent must inspect the actual checkout diff against each lease before accepting a worker report
|
||||
- Parent agent owns Truth Document acceptance, lease validation, and final report
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
@@ -75,6 +85,11 @@ Truthmark hierarchy:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- block 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 required report fields before accepting it
|
||||
- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
description: 'Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.'
|
||||
---
|
||||
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml
|
||||
- docs/truthmark/areas.md
|
||||
- relevant child route files under docs/truthmark/areas/
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/areas.md
|
||||
- truth doc: docs/truth/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truth/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Blocking ambiguity:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -8,7 +8,7 @@ name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
description: 'Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, or needs split/repair. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.'
|
||||
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.'
|
||||
---
|
||||
|
||||
---
|
||||
name: truthmark-structure
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, or needs split/repair. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
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.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
@@ -23,6 +23,13 @@ Implementation code and canonical truth docs are inspected evidence for current
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
|
||||
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
|
||||
Copilot custom-agent mode:
|
||||
- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
|
||||
- dispatch read-only project custom agents only: @truth-route-auditor
|
||||
- custom agents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns all Truth Structure writes and final topology decisions
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
@@ -32,6 +39,21 @@ Teams may edit the template files under docs/templates/ to define their local tr
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
|
||||
- preserve unrelated authored content
|
||||
## 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 block for 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. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
@@ -111,6 +133,11 @@ Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
Initial truth boundary:
|
||||
- Area: Authentication
|
||||
- Code: src/auth/**
|
||||
- Truth owner: docs/truth/authentication/session.md
|
||||
- Scope: session behavior only
|
||||
Truth docs created:
|
||||
- docs/truth/authentication/session.md
|
||||
Truth docs split:
|
||||
|
||||
@@ -8,7 +8,7 @@ name: truthmark-sync
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
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.
|
||||
@@ -22,7 +22,17 @@ Parent workflow:
|
||||
4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
|
||||
6. 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.
|
||||
Copilot custom-agent mode:
|
||||
- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
|
||||
- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier
|
||||
- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer
|
||||
- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
|
||||
- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
|
||||
- parent must inspect the actual checkout diff against each lease before accepting a worker report
|
||||
- Parent agent owns Truth Sync acceptance, lease validation, and final report
|
||||
Topology quality gate:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
|
||||
@@ -80,31 +90,11 @@ Truthmark hierarchy:
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
### Truth Sync Worker
|
||||
The parent provides the task focus and any repository context already gathered.
|
||||
Worker rules:
|
||||
- inspect relevant staged, unstaged, and untracked functional code directly
|
||||
- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly
|
||||
- Code verification is parent-owned; report what was run or why it was not run
|
||||
- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
|
||||
- must not rewrite functional code
|
||||
Return result in this shape:
|
||||
- status: completed | blocked
|
||||
- changedCodeReviewed: string[]
|
||||
- ownershipReviewed: string[]
|
||||
- structureRequired?: string[]
|
||||
- truthDocsUpdated: string[]
|
||||
- routingDocsUpdated: string[]
|
||||
- truthDocsSplit?: string[]
|
||||
- evidenceChecked: { claim: string; evidence: string[]; result: supported | narrowed | removed | blocked }[]
|
||||
- notes: string[]
|
||||
- blockedReason?: string
|
||||
- manualReviewFiles?: string[]
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and docs/truthmark/areas.md changed during sync
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- block on any unrelated diff caused by the sync step
|
||||
- block if functional code changed during sync
|
||||
- verify the worker report matches the required headings and sections
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, Evidence, and Result entries under Evidence checked
|
||||
- verify the updated docs correspond to the reviewed changed-code surface
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired
|
||||
|
||||
Reference in New Issue
Block a user