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
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-guide
|
||||
last_reviewed: 2026-05-13
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- repo-rules.md
|
||||
- ../README.md
|
||||
@@ -47,7 +47,7 @@ Read:
|
||||
1. [.truthmark/config.yml](../../.truthmark/config.yml)
|
||||
2. [docs/truth/workflows/overview.md](../truth/workflows/overview.md) and the relevant workflow leaf doc under `docs/truth/workflows/`
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
|
||||
4. [docs/ai/agent-skills-workflow-review.md](agent-skills-workflow-review.md)
|
||||
4. The manifest, renderer, generated surfaces, and focused tests named by the workflow truth docs
|
||||
|
||||
### Package version changes
|
||||
|
||||
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-guide
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- repo-rules.md
|
||||
- ../truth/workflows/overview.md
|
||||
- ../truth/workflows/shared-gates.md
|
||||
- ../../src/agents/workflow-manifest.ts
|
||||
- ../../.codex/skills/truthmark-sync/SKILL.md
|
||||
- ../../.codex/skills/truthmark-structure/SKILL.md
|
||||
- ../../.codex/skills/truthmark-document/SKILL.md
|
||||
- ../../.codex/skills/truthmark-realize/SKILL.md
|
||||
- ../../.codex/skills/truthmark-check/SKILL.md
|
||||
- https://developers.openai.com/codex/skills
|
||||
- https://developers.openai.com/blog/eval-skills
|
||||
- https://developers.openai.com/blog/skills-shell-tips
|
||||
- https://developers.openai.com/blog/skills-agents-sdk
|
||||
- https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
|
||||
- https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
|
||||
- https://code.claude.com/docs/en/slash-commands
|
||||
- https://agentskills.io/specification
|
||||
- https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity
|
||||
---
|
||||
|
||||
This note summarizes external skill-authoring guidance reviewed on 2026-05-15 and applies it to Truthmark's installed project workflows. It is a reference for future workflow-surface changes, not a replacement for [workflow overview](../truth/workflows/overview.md) and the bounded workflow truth docs under `docs/truth/workflows/`.
|
||||
|
||||
## External Links Reviewed
|
||||
|
||||
All external links in `source_of_truth` resolved on 2026-05-15. The previous Anthropic Claude Code slash-command URL redirects to `https://code.claude.com/docs/en/slash-commands`; use the canonical redirected URL in this doc.
|
||||
|
||||
The Perplexity review adds a stricter standard than this doc previously stated: description metadata is routing logic, not a compact summary of the workflow. Expected outputs and success criteria belong in the body, report contract, or eval rubric.
|
||||
|
||||
## Skill Design Standard
|
||||
|
||||
Agent skills are context packages, not human manuals. Every skill is a tax paid by every session at the metadata layer and by every loaded conversation at the body layer. Add or grow a skill only when representative agents fail, behave inconsistently, or need durable project-specific context that the base model would not reliably infer.
|
||||
|
||||
Use progressive disclosure:
|
||||
|
||||
- metadata: `name` and `description` decide whether the skill loads
|
||||
- body: the short core procedure, boundaries, gotchas, and report shape
|
||||
- bundled files: scripts, references, assets, or config loaded only when needed
|
||||
|
||||
Descriptions are the hardest line. They should be short routing triggers, ideally 50 words or fewer, written as "Use when..." or "Load when..." with user intent, symptoms, and adjacent-workflow exclusions. They must not summarize the workflow steps, duplicate the body, or promise outputs.
|
||||
|
||||
Skill bodies should skip obvious mechanics the model already knows. Keep opinionated boundaries, gotchas, failure modes, negative examples, and high-value judgment rules. Move heavy, rare, or mutually exclusive material into explicitly named reference files only when each supported host can expose and load those files reliably.
|
||||
|
||||
Use scripts only for deterministic repeated mechanics the agent would otherwise reinvent. Leave interpretation, comparison, ownership decisions, and reporting to the model unless a deterministic checker can enforce them better than prose.
|
||||
|
||||
## Evaluation Standard
|
||||
|
||||
Reliable skills need evals before or alongside skill changes, not only syntax checks. For workflow-surface changes, maintain three classes of cases:
|
||||
|
||||
- positive routing: the workflow loads when its real trigger appears
|
||||
- negative routing: the workflow stays unloaded for nearby but wrong tasks
|
||||
- forbidden adjacency: the workflow does not steal requests from a sibling workflow
|
||||
|
||||
Useful eval suites cover loading precision/recall, required file reads, forbidden loads, progressive reference reads, end-to-end task completion, and cross-host behavior where hosts differ. Deterministic tests can prove rendered metadata, required routing cues, report headings, write-boundary text, and stale-surface diagnostics. Prompt-style agent evals are smoke checks and examples, not proof of universal routing correctness.
|
||||
|
||||
Maintenance should be append-mostly. Add gotchas when agents fail, tighten descriptions only with routing evals, and re-check nearby workflows when any description changes. A changed description can break workflows that were not edited.
|
||||
|
||||
Security posture matters because skills can contain instructions, scripts, assets, dependencies, and network instructions. Treat installed skills as executable agent runtime: inspect bundled files, scripts, dependency behavior, and any network instruction before trusting them.
|
||||
|
||||
## Truthmark Workflow Inventory
|
||||
|
||||
Truthmark currently installs five workflows across host-specific surfaces:
|
||||
|
||||
| Workflow | Main purpose | Codex implicit policy |
|
||||
| --- | --- | --- |
|
||||
| `truthmark-sync` | Finish-time code-to-truth synchronization after functional code changes | `allow_implicit_invocation: true` |
|
||||
| `truthmark-structure` | Design or repair truth routing topology | `allow_implicit_invocation: false` |
|
||||
| `truthmark-document` | Document existing implemented behavior without code changes | `allow_implicit_invocation: false` |
|
||||
| `truthmark-realize` | Realize truth docs into functional code | `allow_implicit_invocation: false` |
|
||||
| `truthmark-check` | Audit repository truth health | `allow_implicit_invocation: false` |
|
||||
|
||||
Generated runtime surfaces include `.codex/skills/`, `.claude/skills/`, `.opencode/skills/`, `.github/prompts/`, `.gemini/commands/truthmark/`, and compact managed instruction blocks in files such as `AGENTS.md`.
|
||||
|
||||
Current strengths:
|
||||
|
||||
- The workflow split is coherent: Structure owns topology, Document owns implemented behavior without code changes, Sync owns code-first finish-time alignment, Realize owns doc-first code changes, and Check owns audit.
|
||||
- Write boundaries are unusually clear. The skills repeatedly state which docs, routing files, or functional code may be changed.
|
||||
- The runtime is agent-native. Skills tell agents to inspect the checkout directly and treat the CLI as optional validation rather than a required orchestration bridge.
|
||||
- The managed instruction block is compact while detailed procedures live in explicit workflow surfaces, preserving ordinary task context.
|
||||
- Codex metadata correctly makes only Sync implicitly invocable. Manual workflows remain explicit in Codex, reducing accidental Structure, Document, Realize, or Check runs.
|
||||
- Generated-surface tests cover parseable frontmatter, required phrases, report headings, host paths, version markers, and stale-surface diagnostics.
|
||||
|
||||
## Current Findings
|
||||
|
||||
1. Medium: workflow evals should test routing, not just rendered text.
|
||||
Existing deterministic tests prove surfaces contain required words. Add positive, negative, and forbidden-adjacency cases for each workflow description before changing metadata. A useful first suite can run against generated descriptions without invoking a live model.
|
||||
|
||||
2. Medium: body growth must stay progressive.
|
||||
Repeated hierarchy, decision-truth, ownership, evidence, and preservation gates are defensible because generated host surfaces must stand alone. If bodies grow substantially, split shared guidance into generated references only after every supported host reliably exposes those references and tests prove agents read them when needed.
|
||||
|
||||
3. Low: external links should stay canonical and dated.
|
||||
Link review should update redirects, add review dates, and keep volatile external guidance in this reference doc rather than embedded directly in runtime workflow bodies.
|
||||
|
||||
Resolved:
|
||||
|
||||
- Resolved 2026-05-13: `truthmark-document` metadata now names Truth Sync, Truth Check, and Truth Structure as workflows that can hand off missing implemented-behavior documentation.
|
||||
- Resolved 2026-05-13: `truthmark-sync` frontmatter and Codex metadata now include skip cases for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, and no functional code changes.
|
||||
- Resolved 2026-05-15: external source links were reviewed, the Claude Code slash-command link was canonicalized, and the Perplexity skill-maintenance standard was incorporated.
|
||||
- Resolved 2026-05-15: workflow frontmatter descriptions now include adjacent-workflow exclusions without summarizing the full workflow body.
|
||||
- Resolved 2026-05-15: workflow metadata and routing-eval expectations now live in a typed manifest consumed by generated surfaces and deterministic tests.
|
||||
|
||||
## Routing Eval Matrix
|
||||
|
||||
| Workflow | Positive trigger examples | Negative trigger examples | Forbidden adjacency | Key success checks |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync | "I changed session code; finish and sync truth" | docs-only edit, formatting-only edit, no functional code diff | must not handle doc-first implementation or manual topology design | reads changed code and routing, updates only truth docs or routing, reports skipped or blocked correctly |
|
||||
| Structure | "split broad repository routing into auth and billing" | "document current auth behavior" | must not implement code or patch mixed-owner docs as shape repair | repairs route topology before docs, creates bounded starter docs, preserves authored content and decisions/rationale |
|
||||
| Document | "document existing order submission behavior" | "implement the behavior in this truth doc" | must not handle functional-code changes that require Sync | reads code and tests, writes docs/routing only, does not edit functional code |
|
||||
| Realize | "realize docs/truth/auth/session-timeout.md into code" | "sync docs after my code change" | must not edit truth docs or routing | reads truth docs first, blocks on stale/mixed-owner source truth, edits functional code only, runs relevant tests |
|
||||
| Check | "audit truth health before review" | "run lint and tests" | must not replace ordinary verification or finish-time Sync | reports issues and suggested fixes, optionally runs `truthmark check`, does not silently rewrite unrelated files |
|
||||
|
||||
## Maintenance Rules
|
||||
|
||||
- Add deterministic description-quality tests that require positive, negative, and forbidden-adjacency routing cues in every generated `SKILL.md` description.
|
||||
- Keep generated workflow descriptions, Codex metadata, routing examples, gate lists, write boundaries, and report-section expectations in the typed workflow manifest.
|
||||
- Treat prompt-style agent evals, if added, as smoke checks and examples rather than proof of universal routing correctness.
|
||||
- Tighten `truthmark-check` descriptions before adding more workflows.
|
||||
- Keep generated skill bodies below the point where common guidance crowds out workflow-specific procedure.
|
||||
- Re-audit security posture before any Truthmark skill gains scripts, assets, network-capable dependencies, or generated reference files.
|
||||
- When an agent failure reveals a workflow gotcha, add the gotcha to the smallest owning workflow body or shared gate rather than rewriting broad instructions.
|
||||
+10
-2
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-rules
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../AGENTS.md
|
||||
- ../README.md
|
||||
@@ -28,7 +28,7 @@ Code is the implementation. On code/doc conflict, inspect code, decide whether c
|
||||
|
||||
## Product Boundary
|
||||
|
||||
Truthmark public CLI commands are `config`, `init`, `check`, `index`, `impact`, and `context`. Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands.
|
||||
Truthmark public CLI commands are `config`, `init`, `check`, `index`, `impact`, and `context`. Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands.
|
||||
|
||||
Agents inspect the active checkout directly. There is no daemon, database, remote service, or V1 MCP server.
|
||||
|
||||
@@ -49,6 +49,14 @@ Agents inspect the active checkout directly. There is no daemon, database, remot
|
||||
13. Verify the text and file contracts that changed with the narrowest evidence that can falsify them: generated diffs, structured parsers, snapshots, fixture round-trips, build/package/check commands, or focused tests. Do not run broad tests as ceremony when they add no evidence; state skipped checks.
|
||||
14. Work surgically and fail visibly: surface assumptions, conflicts, skipped files, blocked ownership, and unverified claims; touch only request-traceable lines, match existing style, checkpoint long workflow or skill edits, and report unrelated issues instead of editing them.
|
||||
|
||||
## Instruction Surface Boundary
|
||||
|
||||
In `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md`, only text between `<!-- truthmark:start -->` and `<!-- truthmark:end -->` is the generated Truthmark workflow surface. Repo-local preamble outside those markers should delegate to this file and conditional routing docs, not duplicate completion policy. Do not put this repository's internal policy, completion gates, or maintainer-only standards inside marker-delimited blocks, package templates, installed workflow skills, prompts, or downstream scaffold output.
|
||||
|
||||
## Completion Gate
|
||||
|
||||
Before declaring changed repository work complete, apply [docs/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) and [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md). Skip this gate only for read-only or no-file-change sessions, and state the skip reason when completion or verification would otherwise be expected.
|
||||
|
||||
## Routing
|
||||
|
||||
Fast task routing lives in [agent-onboarding.md](agent-onboarding.md). Read only the docs that govern the slice you are changing.
|
||||
|
||||
@@ -39,7 +39,7 @@ This doc covers the current module grouping of the Truthmark codebase and the pr
|
||||
| `src/truth/` | Neutral helpers for truth root resolution and evidence report formatting shared by scaffold, checks, sync, and agent renderers |
|
||||
| `src/git/` | Git repository and worktree resolution plus change listing |
|
||||
| `src/sync/` | Truth Sync policy and completed, skipped, or blocked report rendering |
|
||||
| `src/agents/` | Installed Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check instruction text plus shared worker and skill contract fragments |
|
||||
| `src/agents/` | Installed Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check instruction text plus shared worker and skill contract fragments |
|
||||
| `src/realize/` | Truth Realize report rendering |
|
||||
| `src/output/` | Diagnostic types plus human and JSON rendering shared by CLI and check flows |
|
||||
| `src/types/` | Local type shims |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
last_reviewed: 2026-05-13
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../.truthmark/config.yml
|
||||
- ../truth/contracts.md
|
||||
@@ -36,7 +36,7 @@ The durable surfaces are ordinary repository files:
|
||||
- [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- canonical docs under `docs/`
|
||||
- the managed Truthmark block inside [AGENTS.md](../../AGENTS.md)
|
||||
- generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check surfaces under `.codex/skills/`, `.opencode/skills/`, `.claude/skills/`, `.github/prompts/`, and `.gemini/commands/truthmark/`
|
||||
- generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check surfaces under `.codex/skills/`, `.opencode/skills/`, `.claude/skills/`, `.github/prompts/`, and `.gemini/commands/truthmark/`
|
||||
- Codex workflow metadata under `.codex/skills/truthmark-*/agents/openai.yaml`
|
||||
- configured platform instruction files such as [AGENTS.md](../../AGENTS.md), `CLAUDE.md`, `.github/copilot-instructions.md`, and `GEMINI.md`
|
||||
|
||||
@@ -77,16 +77,16 @@ Key implementation surfaces:
|
||||
|
||||
### Installed workflow support
|
||||
|
||||
Truthmark also contains support primitives for the installed Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check workflows:
|
||||
Truthmark also contains support primitives for the installed Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check workflows:
|
||||
|
||||
- `src/templates/agents-block.ts` renders compact managed instruction blocks
|
||||
- `src/agents/*` renders detailed workflow and skill text for explicit workflow invocation
|
||||
- `src/templates/codex-skills.ts` renders generated skill, prompt, command, and metadata content for configured platforms
|
||||
- `src/templates/workflow-surfaces.ts` renders generated skill, prompt, command, and metadata content for configured platforms
|
||||
- `src/templates/generated-surfaces.ts` assembles configured platform surfaces from the renderers
|
||||
- `src/sync/*` classifies functional-code paths and renders Truth Sync reports
|
||||
- `src/realize/report.ts` renders the Truth Realize completion report shape
|
||||
|
||||
These modules support the installed workflow contract even though V1 does not expose dedicated CLI entrypoints for the installed Truth Structure, Truth Document, Truth Sync, Truth Realize, or Truth Check workflows.
|
||||
These modules support the installed workflow contract even though V1 does not expose dedicated CLI entrypoints for the installed Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, or Truth Check workflows.
|
||||
|
||||
## Architecture Doc Boundary
|
||||
|
||||
@@ -120,7 +120,7 @@ Current automatic coverage discovery scans common roots such as `src/`, `api/`,
|
||||
- `src/checks/areas.ts`
|
||||
- `src/sync/surfaces.ts`
|
||||
- `src/agents/instructions.ts`
|
||||
- `src/templates/codex-skills.ts`
|
||||
- `src/templates/workflow-surfaces.ts`
|
||||
- `src/templates/generated-surfaces.ts`
|
||||
- `src/templates/agents-block.ts`
|
||||
|
||||
|
||||
@@ -38,12 +38,12 @@ Use dates from the current local session date. Keep slugs short, lowercase, and
|
||||
|
||||
## Required Shape
|
||||
|
||||
Each change note must use this structure:
|
||||
Each change note must use this structure when `Version action` is `none`:
|
||||
|
||||
```markdown
|
||||
# Short Change Title
|
||||
|
||||
Version action: none|patch|minor|major
|
||||
Version action: none
|
||||
|
||||
## PR Summary
|
||||
|
||||
@@ -58,11 +58,35 @@ Version action: none|patch|minor|major
|
||||
- Command run, or skipped check with reason.
|
||||
```
|
||||
|
||||
Each change note must use this structure when `Version action` is `patch`, `minor`, or `major`:
|
||||
|
||||
```markdown
|
||||
# Short Change Title
|
||||
|
||||
Previous version: MAJOR.MINOR.PATCH
|
||||
New version: MAJOR.MINOR.PATCH
|
||||
Diff basis: release/MAJOR.MINOR.PATCH..HEAD plus working tree
|
||||
Version action: patch|minor|major
|
||||
SemVer rationale: One sentence explaining why the pending release payload requires this bump.
|
||||
|
||||
Release payload:
|
||||
- Concise maintainer-facing summary of an actual release-worthy change.
|
||||
|
||||
User-facing release text:
|
||||
- User-visible release note.
|
||||
|
||||
Verification:
|
||||
- Command run, or skipped check with reason.
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- `Version action` must match [versioning.md](versioning.md).
|
||||
- If `Version action` is `patch`, `minor`, or `major`, the package version must change in the same working change.
|
||||
- If the package version changes, a matching change note is required because Truthmark releases whenever the package version changes.
|
||||
- If the package version changes, a matching change note for the new version is required because Truthmark releases whenever the package version changes.
|
||||
- Versioned change notes must describe all release-worthy pending changes since the previous release tag, not only the package metadata edit or generated version-marker refresh.
|
||||
- Versioned change notes must name the previous version, new version, diff basis, SemVer rationale, release payload, user-facing release text, and verification.
|
||||
- Verification entries should report final useful checks only; do not include red-test scaffolding, agent mistakes, or process chatter in release-facing change notes.
|
||||
- Internal-only repository standards may use `Version action: none`.
|
||||
- Release notes describe published package behavior, not private repo maintenance.
|
||||
- Keep notes compact; they are source material for PR and release descriptions, not canonical product truth.
|
||||
|
||||
@@ -64,10 +64,17 @@ Treat these as published package behavior:
|
||||
|
||||
## Version Change Procedure
|
||||
|
||||
Before changing a version number:
|
||||
|
||||
1. Identify the previous released version from the latest lower `release/<version>` tag.
|
||||
2. Inspect all pending release payload since that previous version: committed branch diff plus staged, unstaged, and untracked files that will ship.
|
||||
3. Classify the payload with the decision table above before editing `package.json`.
|
||||
4. If the requested new version is lower than the required bump, block the edit and report the required version. Do not accept a patch request for a minor or major payload.
|
||||
|
||||
When changing a version number:
|
||||
|
||||
1. Decide the bump class before editing the version and state the rationale in the handoff, PR, or release note.
|
||||
2. Create or update the matching `changes/` note from [change-notes.md](change-notes.md).
|
||||
1. State the previous version, requested version, required bump class, and SemVer rationale in the handoff, PR, or release note.
|
||||
2. Create or update the matching `changes/` note from [change-notes.md](change-notes.md), covering the full release payload since the previous version.
|
||||
3. Update `package.json` and the root package entries in `package-lock.json` together.
|
||||
4. Rerun `truthmark init` only when the package version actually changes, then inspect generated version-marker diffs.
|
||||
5. Run the focused verification required by [testing-and-verification.md](testing-and-verification.md). For release-sensitive package version changes, `npm run release:check` is the default final gate.
|
||||
@@ -78,6 +85,7 @@ When reporting a package version decision, state only:
|
||||
|
||||
- chosen version action
|
||||
- one-line SemVer rationale
|
||||
- whether the requested version matched the required bump
|
||||
- files changed or intentionally left unchanged
|
||||
- matching change note path when a version changes
|
||||
- verification run or explicitly skipped
|
||||
|
||||
@@ -24,7 +24,7 @@ This document describes the current behavior of `truthmark check`.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
`truthmark check` is validation tooling. It is not the runtime for Truth Sync, Truth Realize, Truth Structure, or Truth Check skills, and it is not a CI-style merge gate by default.
|
||||
`truthmark check` is validation tooling. It is not the runtime for Truth Sync, Truth Preview, Truth Realize, Truth Structure, or Truth Check skills, and it is not a CI-style merge gate by default.
|
||||
|
||||
The command:
|
||||
|
||||
|
||||
+37
-2
@@ -70,6 +70,8 @@ Route files may express `Truth documents` in either of these forms:
|
||||
|
||||
New scaffolded child route files use the fenced YAML form so routed truth kind is explicit from the first generated route. The legacy list form remains a compatibility input for existing repositories.
|
||||
|
||||
Markdown list values normalize Prettier-escaped glob stars before route matching, so formatted entries such as `src/example/\*\*` are treated as `src/example/**`.
|
||||
|
||||
Supported routed truth kinds are:
|
||||
|
||||
- `behavior`
|
||||
@@ -163,7 +165,7 @@ The command emits `action` diagnostics describing whether each scaffolded file w
|
||||
`truthmark init` requires an existing valid `.truthmark/config.yml`. It does not create config; `truthmark config` is the required first step in a new repository.
|
||||
Configured `instruction_targets` are generated or refreshed independently of platform-specific surfaces, so `AGENTS.md` remains managed even when `claude-code` is not in `platforms`.
|
||||
|
||||
Generated Truth Structure, Truth Document, Truth Sync, and Truth Check surfaces and the managed `AGENTS.md` block use the `truth-sync` diagnostic category.
|
||||
Generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Check, Codex, Claude Code, GitHub Copilot, and OpenCode verifier or leased doc-writer agent surfaces, and the managed `AGENTS.md` block use the `truth-sync` diagnostic category.
|
||||
|
||||
Current agent-native scaffold targets include:
|
||||
|
||||
@@ -177,16 +179,41 @@ Current agent-native scaffold targets include:
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-preview/SKILL.md`
|
||||
- `.codex/skills/truthmark-preview/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-*/support/procedure.md`
|
||||
- `.codex/skills/truthmark-*/support/report-template.md`
|
||||
- `.codex/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance
|
||||
- `.codex/agents/truth-route-auditor.toml`
|
||||
- `.codex/agents/truth-claim-verifier.toml`
|
||||
- `.codex/agents/truth-doc-reviewer.toml`
|
||||
- `.codex/agents/truth-doc-writer.toml`
|
||||
- `.claude/skills/truthmark-structure/SKILL.md`
|
||||
- `.claude/skills/truthmark-document/SKILL.md`
|
||||
- `.claude/skills/truthmark-sync/SKILL.md`
|
||||
- `.claude/skills/truthmark-realize/SKILL.md`
|
||||
- `.claude/skills/truthmark-check/SKILL.md`
|
||||
- `.claude/skills/truthmark-preview/SKILL.md`
|
||||
- `.claude/skills/truthmark-*/support/procedure.md`
|
||||
- `.claude/skills/truthmark-*/support/report-template.md`
|
||||
- `.claude/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance
|
||||
- `.claude/agents/truth-route-auditor.md`
|
||||
- `.claude/agents/truth-claim-verifier.md`
|
||||
- `.claude/agents/truth-doc-reviewer.md`
|
||||
- `.claude/agents/truth-doc-writer.md`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-document/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `.opencode/skills/truthmark-preview/SKILL.md`
|
||||
- `.opencode/skills/truthmark-*/support/procedure.md`
|
||||
- `.opencode/skills/truthmark-*/support/report-template.md`
|
||||
- `.opencode/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance
|
||||
- `.opencode/agents/truth-route-auditor.md`
|
||||
- `.opencode/agents/truth-claim-verifier.md`
|
||||
- `.opencode/agents/truth-doc-reviewer.md`
|
||||
- `.opencode/agents/truth-doc-writer.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `.github/copilot-instructions.md`
|
||||
@@ -195,14 +222,22 @@ Current agent-native scaffold targets include:
|
||||
- `.github/prompts/truthmark-sync.prompt.md`
|
||||
- `.github/prompts/truthmark-realize.prompt.md`
|
||||
- `.github/prompts/truthmark-check.prompt.md`
|
||||
- `.github/prompts/truthmark-preview.prompt.md`
|
||||
- `.github/agents/truth-route-auditor.agent.md`
|
||||
- `.github/agents/truth-claim-verifier.agent.md`
|
||||
- `.github/agents/truth-doc-reviewer.agent.md`
|
||||
- `.github/agents/truth-doc-writer.agent.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/document.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
- `.gemini/commands/truthmark/preview.toml`
|
||||
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style, Claude Code, and OpenCode-style skill indexers can parse every generated workflow surface. Generated Copilot prompt files use `.github/prompts/*.prompt.md` files with `agent` and `description` frontmatter so supported Copilot IDEs can expose `/truthmark-*` prompts. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Managed instruction blocks also render the Truthmark package version, and `package.json` is the single maintained version source for those markers. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` alongside `GEMINI.md`. Re-running `truthmark init` after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style, Claude Code, and OpenCode-style skill indexers can parse every generated workflow surface. For those skill-package hosts, `SKILL.md` is the compact routing and quick-procedure entrypoint; detailed procedure text, report templates, and subagent or lease reference material live in generated sibling `support/*.md` files. Generated Copilot prompt files use `.github/prompts/*.prompt.md` files with `agent` and `description` frontmatter so supported Copilot IDEs can expose `/truthmark-*` prompts. Generated verifier agents are read-only and context-bounded to parent-assigned shards, while generated `truth-doc-writer` agents are write-capable only through parent-provided leases and parent diff validation. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Managed instruction blocks also render the Truthmark package version, and `package.json` is the single maintained version source for those markers. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:preview`, `/truthmark:realize`, and `/truthmark:check` alongside `GEMINI.md`. Re-running `truthmark init` after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.
|
||||
|
||||
The OpenCode `truth-doc-writer` edit allow-list is rendered from the active `docs.roots.truth`, `docs.routing.root_index`, and `docs.routing.area_files_root` config paths so valid leases remain writable in non-default documentation layouts.
|
||||
|
||||
## Check Result Data
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-14
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../src/config/defaults.ts
|
||||
- ../../src/fs/paths.ts
|
||||
@@ -10,7 +10,7 @@ source_of_truth:
|
||||
- ../../src/init/hierarchy.ts
|
||||
- ../../src/templates/init-files.ts
|
||||
- ../../src/templates/agents-block.ts
|
||||
- ../../src/templates/codex-skills.ts
|
||||
- ../../src/templates/workflow-surfaces.ts
|
||||
- ../../src/templates/generated-surfaces.ts
|
||||
---
|
||||
|
||||
@@ -67,35 +67,59 @@ Current scaffold targets:
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-preview/SKILL.md`
|
||||
- `.codex/skills/truthmark-preview/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-*/support/procedure.md`
|
||||
- `.codex/skills/truthmark-*/support/report-template.md`
|
||||
- `.codex/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance
|
||||
- `.codex/agents/truth-route-auditor.toml`
|
||||
- `.codex/agents/truth-claim-verifier.toml`
|
||||
- `.codex/agents/truth-doc-reviewer.toml`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-document/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `.opencode/skills/truthmark-preview/SKILL.md`
|
||||
- `.opencode/skills/truthmark-*/support/procedure.md`
|
||||
- `.opencode/skills/truthmark-*/support/report-template.md`
|
||||
- `.opencode/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance
|
||||
- `.opencode/agents/truth-route-auditor.md`
|
||||
- `.opencode/agents/truth-claim-verifier.md`
|
||||
- `.opencode/agents/truth-doc-reviewer.md`
|
||||
- `.claude/skills/truthmark-structure/SKILL.md`
|
||||
- `.claude/skills/truthmark-document/SKILL.md`
|
||||
- `.claude/skills/truthmark-sync/SKILL.md`
|
||||
- `.claude/skills/truthmark-realize/SKILL.md`
|
||||
- `.claude/skills/truthmark-check/SKILL.md`
|
||||
- `.claude/skills/truthmark-preview/SKILL.md`
|
||||
- `.claude/skills/truthmark-*/support/procedure.md`
|
||||
- `.claude/skills/truthmark-*/support/report-template.md`
|
||||
- `.claude/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/prompts/truthmark-structure.prompt.md`
|
||||
- `.github/prompts/truthmark-document.prompt.md`
|
||||
- `.github/prompts/truthmark-sync.prompt.md`
|
||||
- `.github/prompts/truthmark-realize.prompt.md`
|
||||
- `.github/prompts/truthmark-check.prompt.md`
|
||||
- `.github/prompts/truthmark-preview.prompt.md`
|
||||
- `.github/agents/truth-route-auditor.agent.md`
|
||||
- `.github/agents/truth-claim-verifier.agent.md`
|
||||
- `.github/agents/truth-doc-reviewer.agent.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/document.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
- `.gemini/commands/truthmark/preview.toml`
|
||||
|
||||
`instruction_targets` controls shared managed-instruction files such as `AGENTS.md`. These targets are written or refreshed whenever `truthmark init` runs with a valid config, independent of the configured platform list.
|
||||
`platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs both `CLAUDE.md` and project skills under `.claude/skills/`, which surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check`. GitHub Copilot installs both `.github/copilot-instructions.md` and prompt files under `.github/prompts/`, which surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs. Gemini installs both `GEMINI.md` and project-scoped TOML commands under `.gemini/commands/truthmark/`, which surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
|
||||
`platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs `CLAUDE.md`, project skills under `.claude/skills/`, and verifier plus leased doc-writer subagents under `.claude/agents/`; skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check`, while the generated project subagents provide bounded evidence checks and parent-leased truth-doc writes. GitHub Copilot installs `.github/copilot-instructions.md`, prompt files under `.github/prompts/`, and verifier plus leased doc-writer custom agents under `.github/agents/`; prompts surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs, while Copilot CLI can dispatch the generated `@truth-*` custom agents for bounded evidence checks or parent-leased doc shards. Gemini installs both `GEMINI.md` and project-scoped TOML commands under `.gemini/commands/truthmark/`, which surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:preview`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
|
||||
|
||||
`ensureRepoFile` is intentionally conservative: existing non-empty files are left alone. The AGENTS managed block is the exception because Truthmark owns that block and may refresh it to match current template behavior.
|
||||
|
||||
The generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, Claude Code project skills, GitHub Copilot prompt files, and OpenCode skills keep matching the installed workflow contract. Generated skills, Codex metadata, Copilot prompt files, and managed instruction blocks include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
The generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, Claude Code project skills, GitHub Copilot prompt and custom-agent files, and OpenCode skills keep matching the installed workflow contract. Generated skill packages keep `SKILL.md` compact and write heavy procedure, report-template, and subagent or lease reference material into sibling `support/*.md` files. Generated skills, support files, Codex metadata, Copilot prompt files, Copilot custom-agent files, and managed instruction blocks include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
## AGENTS Management Rules
|
||||
|
||||
@@ -108,7 +132,7 @@ The current managed-instruction update behavior is:
|
||||
- normalize legacy unconditional docs-map and onboarding preamble lines to conditional reads so normal sessions do not load routing docs before they are needed
|
||||
- append the managed block when no block exists
|
||||
- keep the generated workflow block as a compact automatic-Sync trigger and boundary index so it does not consume unnecessary model context in long legacy instruction files
|
||||
- keep detailed report examples, platform-specific invocation strings, and long workflow procedure in explicit generated skill files instead of host instruction blocks
|
||||
- keep detailed report examples, platform-specific invocation strings, and long workflow procedure in explicit generated skill support files or standalone prompt and command files instead of host instruction blocks
|
||||
- preserve repository instruction authority while clarifying that implementation code and canonical truth docs are behavior evidence, not a way to override workflow write boundaries
|
||||
|
||||
Repository-specific instructions should therefore live outside the managed block.
|
||||
@@ -140,10 +164,10 @@ Important current defaults:
|
||||
- default truth scaffolding creates an index at `<truth-root>/README.md`, an index at `<truth-root>/<default-area>/README.md`, six editable templates under `docs/templates/*.md`, and a bounded leaf truth doc at `<truth-root>/<default-area>/overview.md` routed through explicit `{ path, kind }` metadata
|
||||
- default platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`
|
||||
- shared instruction targets are refreshed independently of platform-specific surfaces
|
||||
- explicit Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check surfaces are installed only for configured platforms
|
||||
- explicit Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check surfaces are installed only for configured platforms
|
||||
- installed workflows are agent-native; generated skills tell agents to inspect the checkout directly
|
||||
- generated workflow surfaces leave Truth Sync subagent selection to the acting agent and host environment
|
||||
- managed instruction blocks include only compact hierarchy, decision-truth, automatic-Sync trigger, boundary reminders, and a pointer to explicit workflows; generated skills carry invocation strings and detailed workflow bodies
|
||||
- Codex platform generation includes `.codex/agents/*.toml`, Claude Code platform generation includes `.claude/agents/*.md`, GitHub Copilot platform generation includes `.github/agents/*.agent.md`, and OpenCode platform generation includes `.opencode/agents/*.md` read-only verifier agents plus `truth-doc-writer` for parent-leased Truth Sync and Truth Document shards; the acting parent agent may use them automatically when the host supports subagent dispatch, and read-only verifier agents are context-bounded so they do not preload repo-wide instruction or policy docs unless assigned as evidence
|
||||
- managed instruction blocks include only compact hierarchy, decision-truth, automatic-Sync trigger, boundary reminders, and a pointer to explicit workflows; generated skill entrypoints carry invocation strings and link to support files for detailed workflow bodies
|
||||
- generated workflow surfaces must not demote repository instruction docs such as [docs/ai/repo-rules.md](../ai/repo-rules.md) when warning agents that product truth cannot override workflow write boundaries
|
||||
- scaffolded default standards include AI-native topology repair guidance and an architecture-vs-behavior boundary so new repositories do not rely on human folder discipline
|
||||
- Truth Sync is the only generated skill with implicit invocation enabled because it is the automatic finish-time workflow
|
||||
@@ -155,7 +179,7 @@ Important current defaults:
|
||||
|
||||
Current init JSON reporting uses:
|
||||
|
||||
- `truth-sync` for the managed `AGENTS.md` block and generated Truth Structure, Truth Document, Truth Sync, and Truth Check assets
|
||||
- `truth-sync` for the managed `AGENTS.md` block and generated Truth Structure, Truth Document, Truth Sync, Truth Preview, and Truth Check assets
|
||||
- `realization` for generated Truth Realize assets
|
||||
- `authority` for [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- `config` for the remaining scaffolded files
|
||||
@@ -173,7 +197,7 @@ Current init JSON reporting uses:
|
||||
- Hierarchical routing is the only scaffold model, and route ownership stays in Markdown route files rather than config.
|
||||
- Init reports migration risk instead of rewriting existing truth doc placement on the user's behalf.
|
||||
- V1 uses configured shared instruction targets such as `AGENTS.md` plus generated skill or command surfaces for host compatibility instead of creating host-specific top-level instruction files for every adapter.
|
||||
- Managed instruction blocks are compact automatic-Sync indexes; generated skills and command files own explicit workflow procedure.
|
||||
- Managed instruction blocks are compact automatic-Sync indexes; generated skill support files, prompt files, and command files own explicit workflow procedure.
|
||||
- Decision (2026-05-15): Repository instruction preambles make docs-map and onboarding reads conditional, and managed instruction blocks omit platform-specific workflow invocation strings so ordinary sessions load less context.
|
||||
- Decision (2026-05-13): `.truthmark/config.yml` and route files are the committed hierarchy contract, so init no longer creates a low-value top-level note.
|
||||
- Decision (2026-05-14): Truth-doc templates are kind-specific under `docs/templates/*.md`; `docs/templates/behavior-doc.md` is the default bounded behavior template and the other five typed templates carry kind-specific required sections.
|
||||
@@ -193,5 +217,5 @@ Keeping typed truth-doc templates in `docs/templates/` gives repository owners o
|
||||
- `src/init/init.ts`
|
||||
- `src/templates/init-files.ts`
|
||||
- `src/templates/agents-block.ts`
|
||||
- `src/templates/codex-skills.ts`
|
||||
- `src/templates/workflow-surfaces.ts`
|
||||
- `src/fs/paths.ts`
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../.truthmark/config.yml
|
||||
- ../../../src/agents/instructions.ts
|
||||
- ../../../src/agents/workflow-manifest.ts
|
||||
- ../../../src/templates/codex-skills.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
- ../../../src/templates/generated-surfaces.ts
|
||||
---
|
||||
|
||||
@@ -26,6 +26,7 @@ This document owns the shared installed-workflow runtime model and generated hos
|
||||
- `truthmark init` refreshes managed instruction blocks and explicit workflow surfaces after configuration or renderer changes.
|
||||
- Explicit host invocations run manual workflows.
|
||||
- Truth Sync is the only automatic finish-time workflow trigger.
|
||||
- Truth Preview is an explicit read-only selector for likely workflow routing before edits; it is intended, not authorized.
|
||||
|
||||
## Inputs
|
||||
|
||||
@@ -43,38 +44,46 @@ Agents inspect the checkout directly, apply workflow boundaries from committed s
|
||||
|
||||
The default platform list includes every supported platform. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`.
|
||||
|
||||
| Platform | Generated surface | Invocation shape |
|
||||
| --- | --- | --- |
|
||||
| `codex` | `.codex/skills/truthmark-*/SKILL.md` plus Codex metadata | `/truthmark-*` or `$truthmark-*` |
|
||||
| `opencode` | `.opencode/skills/truthmark-*/SKILL.md` | `/skill truthmark-*` |
|
||||
| `claude-code` | `.claude/skills/truthmark-*/SKILL.md` | `/truthmark-*` |
|
||||
| `github-copilot` | `.github/prompts/truthmark-*.prompt.md` | `/truthmark-*` in supported Copilot IDEs |
|
||||
| `gemini-cli` | `.gemini/commands/truthmark/*.toml` | `/truthmark:*` |
|
||||
| Platform | Generated surface | Invocation shape |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `codex` | `.codex/skills/truthmark-*/SKILL.md`, `.codex/skills/truthmark-*/support/*.md`, Codex metadata, and `.codex/agents/*.toml` verifier and leased doc-writer agents | `/truthmark-*` or `$truthmark-*` |
|
||||
| `opencode` | `.opencode/skills/truthmark-*/SKILL.md`, `.opencode/skills/truthmark-*/support/*.md`, and `.opencode/agents/*.md` verifier and leased doc-writer subagents | `/skill truthmark-*` |
|
||||
| `claude-code` | `.claude/skills/truthmark-*/SKILL.md`, `.claude/skills/truthmark-*/support/*.md`, and `.claude/agents/*.md` verifier and leased doc-writer subagents | `/truthmark-*`; named subagents such as `truth-route-auditor` |
|
||||
| `github-copilot` | `.github/prompts/truthmark-*.prompt.md` and `.github/agents/*.agent.md` verifier and leased doc-writer agents | `/truthmark-*` in supported Copilot IDEs; `@truth-*` custom agents in Copilot CLI |
|
||||
| `gemini-cli` | `.gemini/commands/truthmark/*.toml` | `/truthmark:*` |
|
||||
|
||||
Generated skill files, Gemini command files, Codex metadata, and managed instruction blocks include the package version from `package.json`. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
Generated skill files, Gemini command files, Codex metadata, Codex custom-agent files, Claude Code subagent files, GitHub Copilot custom-agent files, OpenCode subagent files, and managed instruction blocks include the package version from `package.json`. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
Generated workflow descriptions are routing triggers. They use short positive trigger language plus adjacent-workflow exclusions, and they leave detailed procedure, write boundaries, and report shape to the workflow body.
|
||||
Codex, Claude Code, GitHub Copilot, and OpenCode platform generation include project-scoped read-only verifier agents for workflow-owned subagent dispatch plus a write-capable `truth-doc-writer` for parent-leased Truth Sync and Truth Document shards. Codex exposes `truth_route_auditor`, `truth_claim_verifier`, `truth_doc_reviewer`, and `truth_doc_writer`. Claude Code exposes `truth-route-auditor`, `truth-claim-verifier`, `truth-doc-reviewer`, and `truth-doc-writer` project subagents. GitHub Copilot and OpenCode expose `@truth-route-auditor`, `@truth-claim-verifier`, `@truth-doc-reviewer`, and `@truth-doc-writer`. The parent workflow may use them automatically when the host supports subagents and bounded fan-out is useful; read-only verifier agents keep context bounded by avoiding host instruction files and repo-wide policy docs unless assigned as evidence, write workers require explicit leases, and the parent workflow owns final reports, repo-policy interpretation, diff validation, and acceptance.
|
||||
Read-only verifier agents include an explicit context boundary: they inspect only the parent-assigned shard plus required checkout evidence files and do not preload repo-wide instruction or policy docs unless the parent assigns those files as evidence.
|
||||
|
||||
Generated workflow descriptions are routing triggers. They use short positive trigger language plus adjacent-workflow exclusions. Skill-package hosts keep `SKILL.md` as the compact routing and quick-procedure entrypoint, then put detailed procedure, report templates, and subagent or lease instructions in generated `support/*.md` files. Standalone prompt and command hosts keep the full workflow body inline because they do not load skill-package support files.
|
||||
|
||||
The typed workflow manifest owns generated description text, Codex-facing short descriptions and default prompts, implicit-invocation policy, positive and negative routing examples, forbidden-adjacent cases, required gates, write boundaries, and report-section expectations. Generated host surfaces and deterministic routing tests should consume that manifest rather than duplicating workflow metadata in renderer code.
|
||||
|
||||
Truthmark-owned workflow surfaces are generated under host-specific directories. Repo-root `skills/` files are not generated V1 workflow surfaces.
|
||||
|
||||
Managed instruction blocks are compact automatic-Sync trigger and boundary indexes. They intentionally omit platform-specific invocation strings, non-automatic workflow procedures, report examples, and long checklists. Detailed invocations and procedures live in generated skills, prompts, and command files.
|
||||
Managed instruction blocks are compact automatic-Sync trigger and boundary indexes. They intentionally omit platform-specific invocation strings, non-automatic workflow procedures, report examples, and long checklists. Detailed invocations and procedures live in generated skills, skill support files, prompts, and command files.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Installed skills, prompts, commands, and managed instruction blocks are the workflow runtime. The CLI installs and validates those surfaces but does not orchestrate Truth Sync or require helper payloads before agents can act.
|
||||
- Decision (2026-05-15): Managed instruction blocks stay compact enough for ordinary agent context. Non-automatic workflow procedure belongs in generated skills, prompts, and command files.
|
||||
- Decision (2026-05-15): Managed instruction blocks omit platform-specific invocation strings; host-specific generated workflow files remain the canonical place for invocation detail.
|
||||
- Decision (2026-05-15): Truthmark follows current host discovery paths for generated workflow files: Codex uses `.codex/skills/`, Claude Code uses `.claude/skills/`, GitHub Copilot uses `.github/prompts/`, OpenCode uses `.opencode/skills/`, Gemini CLI uses `.gemini/commands/`, and repo-root `skills/` is not a generated V1 target.
|
||||
- Decision (2026-05-15): Truthmark follows current host discovery paths for generated workflow files: Codex uses `.codex/skills/`, Claude Code uses `.claude/skills/` and `.claude/agents/`, GitHub Copilot uses `.github/prompts/` and `.github/agents/`, OpenCode uses `.opencode/skills/`, Gemini CLI uses `.gemini/commands/`, and repo-root `skills/` is not a generated V1 target.
|
||||
- Decision (2026-05-15): Workflow descriptions are routing triggers rather than workflow summaries; adjacent-workflow exclusions belong in metadata when they prevent wrong workflow loading.
|
||||
- Decision (2026-05-15): Workflow metadata and routing-eval expectations live in a typed manifest so generated descriptions, host metadata, and deterministic routing tests share one structural source.
|
||||
- Decision (2026-05-16): Codex, Claude Code, GitHub Copilot, and OpenCode may install project-scoped read-only verifier agents plus a leased `truth-doc-writer`; parent workflows keep acceptance and diff validation ownership and do not require users to request subagents per task.
|
||||
- Decision (2026-05-16): Read-only verifier agents do not preload host instruction files or repo-wide policy docs by default; parent workflows keep that policy context and pass only bounded evidence shards to verifier agents.
|
||||
- Decision (2026-05-16): Coding and document-writing speed is not a priority over workflow simplicity and agent stability. Truthmark must not make document writing faster by adding project complexity, weaker leases, broader write authority, or less stable agent behavior.
|
||||
- Decision (2026-05-16): Truth Preview is generated as an explicit read-only workflow surface, not an automatic gate, validator, or Truth Check replacement.
|
||||
- Decision (2026-05-16): Generated skill packages use progressive disclosure: `SKILL.md` stays compact for routing and first-step execution, while heavy procedure detail, report examples, and subagent or lease reference material move to generated support files beside the skill.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping workflow execution agent-native makes installed repositories usable even when the Truthmark package is unavailable at execution time. Agents can read committed surfaces, inspect the checkout, and act without depending on a daemon, database, or mandatory generated payload.
|
||||
|
||||
Compact managed instruction blocks protect ordinary model context while explicit workflow surfaces remain available when the agent needs a full procedure.
|
||||
Compact managed instruction blocks and compact skill entrypoints protect ordinary model context while explicit support files, prompt files, and command files remain available when the agent needs a full procedure.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ This document owns shared ownership, evidence, shape-repair, architecture-bounda
|
||||
|
||||
## Triggers
|
||||
|
||||
The gates apply whenever Truth Structure, Truth Document, Truth Sync, Truth Realize, or Truth Check reads, writes, audits, or relies on canonical truth docs.
|
||||
The gates apply whenever Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, or Truth Check reads, writes, audits, or relies on canonical truth docs.
|
||||
|
||||
## Inputs
|
||||
|
||||
|
||||
@@ -2,11 +2,12 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-check.ts
|
||||
- ../../../src/checks/**
|
||||
- ../../../src/agents/shared.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
---
|
||||
|
||||
# Truth Check Workflow
|
||||
@@ -33,7 +34,7 @@ Truth Check owns agent-led truth-health review. It reports issues and suggested
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Check inspects the checkout directly and may optionally run `truthmark check` when local tooling is available. Installed workflows must not depend on the binary being present.
|
||||
Truth Check inspects the checkout directly and may optionally run `truthmark check` when local tooling is available. Installed workflows must not depend on the binary being present. In Codex, Claude Code, GitHub Copilot, or OpenCode, Truth Check may automatically use generated read-only verifier subagents when the host supports subagent dispatch and the parent agent chooses bounded fan-out.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
@@ -43,12 +44,15 @@ Truth Check supports each finding and suggested fix with evidence from config, r
|
||||
|
||||
If follow-up docs edits are needed for mixed-owner docs, Truth Check runs or recommends Truth Structure before editing.
|
||||
|
||||
When subagent mode is available, the parent agent may dispatch read-only route, claim, and doc-shape verifier workers across bounded shards. Codex exposes `truth_route_auditor`, `truth_claim_verifier`, and `truth_doc_reviewer`; Claude Code exposes `truth-route-auditor`, `truth-claim-verifier`, and `truth-doc-reviewer` project subagents; GitHub Copilot and OpenCode expose `@truth-route-auditor`, `@truth-claim-verifier`, and `@truth-doc-reviewer`. Workers return structured findings only and must not edit files. They inspect only the parent-assigned shard plus required checkout evidence files and do not preload repo-wide instruction or policy docs unless the parent assigns those files as evidence. The parent agent deduplicates findings, spot-checks evidence, optionally runs validation, and owns repo-policy interpretation and the final Truth Check report.
|
||||
|
||||
Completed reports include `Files reviewed`, `Issues found`, `Fixes suggested`, `Evidence checked`, and `Validation`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Check is an audit workflow, not a substitute for lint, tests, typecheck, code review, or Truth Sync.
|
||||
- Decision (2026-05-15): Truth Check reports mixed-owner truth docs as topology issues and does not silently repair them outside the proper workflow.
|
||||
- Decision (2026-05-16): Codex, Claude Code, GitHub Copilot, and OpenCode subagent mode is read-only, automatic when host-supported, parent-owned, and context-bounded; verifier agents may gather evidence but never write docs, preload repo-wide policy unless assigned, or replace the final audit report.
|
||||
|
||||
## Rationale
|
||||
|
||||
|
||||
@@ -2,10 +2,12 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-document.ts
|
||||
- ../../../src/agents/write-lease.ts
|
||||
- ../../../src/agents/shared.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
---
|
||||
|
||||
# Truth Document Workflow
|
||||
@@ -32,7 +34,7 @@ Truth Document owns manual missing-truth generation for implemented behavior. It
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Document is implementation-first and never writes functional code. It documents current implemented behavior only and does not invent future behavior or planned endpoints.
|
||||
Truth Document is implementation-first and never writes functional code. It documents current implemented behavior only and does not invent future behavior or planned endpoints. In Codex, Claude Code, GitHub Copilot, or OpenCode, Truth Document may automatically use generated read-only verifier subagents and explicit-lease `truth-doc-writer` subagents when the host supports subagent dispatch and the parent agent chooses bounded fan-out.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
@@ -46,13 +48,17 @@ When Truth Document restructures a bounded truth doc or runs Structure first, it
|
||||
|
||||
ContextPack may be used to gather bounded source context when available. It does not replace checkout inspection, does not create write permission, and cannot be cited as evidence unless it points to real checkout files, tests, route files, truth docs, schemas, or explicit evidence blocks. If ContextPack is unavailable, Truth Document proceeds manually and reports that repository-intelligence artifacts were not generated.
|
||||
|
||||
When subagent mode is available, the parent agent may dispatch read-only route and claim verifier workers to gather route and evidence findings. Codex exposes `truth_route_auditor` and `truth_claim_verifier`; Claude Code exposes `truth-route-auditor` and `truth-claim-verifier` project subagents; GitHub Copilot and OpenCode expose `@truth-route-auditor` and `@truth-claim-verifier`. Read-only verifier workers inspect only the parent-assigned shard plus required checkout evidence files and do not preload repo-wide instruction or policy docs unless the parent assigns those files as evidence. The same hosts expose `truth_doc_writer` or `@truth-doc-writer` for leased truth-doc shards. The parent agent creates each lease, requires allowedWrites and forbiddenWrites, validates the actual checkout diff against the lease, and owns repo-policy interpretation, final acceptance, routing decisions, shape repair scope, and the final report.
|
||||
|
||||
Completed reports include `Implementation reviewed`, `Ownership reviewed`, `Structure required` when applicable, `Truth docs created`, `Truth docs updated`, `Truth docs restructured`, `Routing updated`, `Evidence checked`, and `Notes`.
|
||||
When write workers are used, each worker report must include `status`, `worker`, `workflow`, `shard`, `filesChanged`, `claimsChecked`, `evidenceChecked`, `offLeaseChanges`, `blockers`, and `notes`. The parent accepts a completed worker report only after validating the parsed report against the lease identity, required report fields, actual worker diff, `allowedWrites`, `forbiddenWrites`, reported `filesChanged`, reported `offLeaseChanges`, and reported `blockers`. Blocked worker reports remain blocked outcomes and must include blockers; off-lease or forbidden actual diffs are rejected rather than trusted from self-report.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Document exists because documenting existing implemented behavior without code changes is not a Truth Sync run.
|
||||
- Decision (2026-05-15): Truth Document must switch to Truth Structure rather than patching mixed-owner truth docs.
|
||||
- Decision (2026-05-15): Truth Document must not lose Product Decisions or Rationale during bounded shape repair or Structure handoff.
|
||||
- Decision (2026-05-16): Codex, Claude Code, GitHub Copilot, and OpenCode subagents may gather bounded read-only evidence for Document without preloading repo-wide policy by default. Document may also dispatch `truth-doc-writer` only with an explicit write lease, while parent agents retain policy, acceptance, and diff-validation ownership.
|
||||
|
||||
## Rationale
|
||||
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-preview.ts
|
||||
- ../../../src/agents/workflow-manifest.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
- ../../../src/templates/generated-surfaces.ts
|
||||
---
|
||||
|
||||
# Truth Preview
|
||||
|
||||
## Scope
|
||||
|
||||
Truth Preview previews likely Truthmark routing before edits.
|
||||
|
||||
It is an explicit read-only planning surface. It is intended, not authorized, and hands off to the selected workflow after user approval.
|
||||
|
||||
## Triggers
|
||||
|
||||
- explicit user invocation through the installed host surface
|
||||
- questions about likely workflow routing, route ownership, target files, write classes, or subagent use before edits
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Preview reads only the context needed to preview ownership:
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- root and child route files
|
||||
- relevant canonical docs
|
||||
- relevant implementation files
|
||||
|
||||
Truth Preview reports the likely Truthmark workflow, why that workflow was selected, likely route owner, expected write classes, expected target files, suggested subagent use, blocking ambiguity, and handoff.
|
||||
|
||||
Truth Preview may suggest the read-only route auditor when bounded verifier input would reduce context or clarify route ownership. It does not use write workers and does not issue write leases.
|
||||
|
||||
Truth Preview must not edit files, create truth docs, update routing, run Truth Sync automatically, replace Truth Check, claim final correctness, issue write leases, or mutate code.
|
||||
|
||||
Completed reports include `Requested outcome`, `Likely workflow`, `Why this workflow`, `Likely route owner`, `Expected write classes`, `Expected target files`, `Suggested subagent use`, `Blocking ambiguity`, and `Handoff`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-16): Truth Preview is a first-class explicit workflow because routing transparency before mutation can prevent agents from loading or acting through the wrong heavier workflow.
|
||||
- Decision (2026-05-16): Truth Preview is not automatic. Its value is a cheap selector for ambiguous routing or write-boundary questions, not a required gate before normal edits.
|
||||
- Decision (2026-05-16): Truth Preview reports intended next steps only; it does not authorize writes or validate final correctness.
|
||||
|
||||
## Rationale
|
||||
|
||||
Preview improves agent performance only when it prevents unnecessary workflow loading, broad context gathering, or wrong-owner edits. Making it automatic would add ceremony and context to straightforward tasks.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no automatic invocation
|
||||
- no validation gate
|
||||
- no Truth Check replacement
|
||||
- no file mutation
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when Preview triggers, read boundaries, report shape, generated surfaces, or handoff behavior change.
|
||||
@@ -2,10 +2,10 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/agents/prompts.ts
|
||||
- ../../../src/templates/codex-skills.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
- ../../../src/realize/report.ts
|
||||
---
|
||||
|
||||
|
||||
@@ -2,10 +2,11 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-structure.ts
|
||||
- ../../../src/agents/shared.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
- ../../../src/routing/**
|
||||
---
|
||||
|
||||
@@ -18,6 +19,7 @@ Truth Structure designs or repairs repository truth topology.
|
||||
## Scope
|
||||
|
||||
Truth Structure owns area routing, child route-file structure, ownership splits, and starter truth-doc placement when topology is missing, stale, broad, overloaded, catch-all, unrouteable, or explicitly requested.
|
||||
Truth Structure also owns new area setup when a user asks to onboard a new code area into Truthmark, a new package/controller/domain lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
|
||||
## Triggers
|
||||
|
||||
@@ -36,6 +38,7 @@ Truth Structure owns area routing, child route-file structure, ownership splits,
|
||||
## Execution Model
|
||||
|
||||
Truth Structure inspects the checkout directly and defines areas by product or behavior ownership, not mechanical directory mirroring.
|
||||
For new area setup, Truth Structure inspects the named code area, infers bounded product or behavior ownership, chooses the owning route when ownership is clear, and otherwise proposes the route and blocks for review. It creates or updates the child route entry or file, creates starter truth docs only where current truth is missing, and reports the initial truth boundary.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
@@ -45,17 +48,22 @@ Topology pressure includes broad code mappings, overloaded child route files, mu
|
||||
|
||||
Truth Structure splits broad, overloaded, catch-all, or mixed-owner areas into behavior-owned route files and bounded leaf truth docs when safe. It updates routing so future Truth Sync can target small docs. If a split is unsafe or ambiguous, it blocks with manual-review files.
|
||||
|
||||
In Codex, Claude Code, GitHub Copilot, and OpenCode, Truth Structure surfaces may reference the generated read-only route auditor when the parent agent chooses bounded validation fan-out. Codex exposes `truth_route_auditor`; Claude Code exposes the `truth-route-auditor` project subagent; GitHub Copilot and OpenCode expose the generated `@truth-route-auditor` custom agent. The route auditor gathers topology and ownership findings only, inspects only the parent-assigned shard plus required checkout evidence files, and does not preload repo-wide instruction or policy docs unless the parent assigns those files as evidence. The parent workflow owns repo-policy interpretation, all route edits, starter truth-doc writes, topology decisions, and the final report.
|
||||
|
||||
Before splitting or restructuring truth docs, Truth Structure inventories Product Decisions and Rationale in every source doc. It moves each current entry into the bounded owner doc it governs, removes or narrows entries only with checkout evidence, and blocks with manual-review files when ownership is unclear.
|
||||
|
||||
Starter truth docs use closed YAML frontmatter with `status`, `doc_type`, `last_reviewed`, and `source_of_truth`, and include `Product Decisions` and `Rationale` sections.
|
||||
New area setup must not edit functional code, perform full behavior documentation unless evidence is inspected and the task explicitly asks for it, patch broad or mixed-owner docs in place, create generic catch-all docs, or treat README files as Sync targets.
|
||||
|
||||
Completed reports include `Topology reviewed`, `Areas reviewed`, `Routing updated`, `Truth docs created`, `Truth docs split`, `Truth docs restructured`, `Evidence checked`, `Topology decisions`, and `Notes`.
|
||||
Completed reports include `Topology reviewed`, `Areas reviewed`, `Routing updated`, `Initial truth boundary`, `Truth docs created`, `Truth docs split`, `Truth docs restructured`, `Evidence checked`, `Topology decisions`, and `Notes`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Structure owns ownership repair. Mixed-owner docs must be split/rerouted when safe, not repaired in place by Sync or Document.
|
||||
- Decision (2026-05-15): Truth Structure must satisfy canonical decision-section expectations for new starter docs and repaired routed docs.
|
||||
- Decision (2026-05-15): Truth Structure must preserve or explicitly account for Product Decisions and Rationale when splitting or restructuring truth docs.
|
||||
- Decision (2026-05-16): Codex, Claude Code, GitHub Copilot, and OpenCode Truth Structure may use the generated read-only route auditor for bounded validation input without preloading repo-wide policy by default, while parent agents retain policy and topology write ownership.
|
||||
- Decision (2026-05-16): New area setup is a Truth Structure scenario, not a separate workflow surface. It may add routing and starter truth docs, but detailed behavior documentation remains bounded by evidence and explicit task scope.
|
||||
|
||||
## Rationale
|
||||
|
||||
@@ -65,7 +73,8 @@ Ownership repair needs a workflow that can change route topology and create boun
|
||||
|
||||
- no mechanical directory mirroring when behavior ownership is clearer
|
||||
- no generic truth docs behind broad catch-all routing
|
||||
- no full behavior documentation during new area setup unless evidence is inspected and the task explicitly asks for it
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when topology pressure signals, split behavior, starter-doc requirements, or Structure report shape changes.
|
||||
Update this doc when topology pressure signals, split behavior, starter-doc requirements, Structure subagent behavior, or Structure report shape changes.
|
||||
|
||||
@@ -2,11 +2,13 @@
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-sync.ts
|
||||
- ../../../src/agents/write-lease.ts
|
||||
- ../../../src/sync/report.ts
|
||||
- ../../../src/agents/shared.ts
|
||||
- ../../../src/templates/workflow-surfaces.ts
|
||||
---
|
||||
|
||||
# Truth Sync Workflow
|
||||
@@ -33,7 +35,7 @@ Truth Sync is code-first. Code leads, truth docs follow, and functional code mus
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Sync may update routed truth docs and routing when routing repair is needed. It may create missing canonical truth docs when routeable implementation would otherwise remain undocumented.
|
||||
Truth Sync may update routed truth docs and routing when routing repair is needed. It may create missing canonical truth docs when routeable implementation would otherwise remain undocumented. In Codex, Claude Code, GitHub Copilot, or OpenCode, Truth Sync may automatically use generated read-only verifier subagents and explicit-lease `truth-doc-writer` subagents when the host supports subagent dispatch and the parent agent chooses bounded fan-out.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
@@ -50,6 +52,7 @@ Truth Sync updates architecture docs in the same sync when changed code alters a
|
||||
ContextPack may be used to accelerate Truth Sync when available. It does not replace checkout inspection, does not create write permission, and cannot be cited as evidence unless it points to real checkout files, tests, route files, truth docs, schemas, or explicit evidence blocks. If ContextPack or ImpactSet is unavailable, Truth Sync proceeds manually and reports that repository-intelligence artifacts were not generated.
|
||||
|
||||
Completed reports include `Changed code reviewed`, `Ownership reviewed`, `Structure required` when applicable, `Truth docs updated`, `Truth docs split` when Structure is run inline, `Evidence checked`, and `Notes`. Skipped reports include `Reason`. Blocked reports include `Reason`, `Files requiring manual review`, and `Next action`.
|
||||
When write workers are used, each worker report must include `status`, `worker`, `workflow`, `shard`, `filesChanged`, `claimsChecked`, `evidenceChecked`, `offLeaseChanges`, `blockers`, and `notes`. The parent accepts a completed worker report only after validating the parsed report against the lease identity, required report fields, actual worker diff, `allowedWrites`, `forbiddenWrites`, reported `filesChanged`, reported `offLeaseChanges`, and reported `blockers`. Blocked worker reports remain blocked outcomes and must include blockers; off-lease or forbidden actual diffs are rejected rather than trusted from self-report.
|
||||
|
||||
Current skip reasons are:
|
||||
|
||||
@@ -61,7 +64,7 @@ Current skip reasons are:
|
||||
|
||||
Truth Sync's generated frontmatter description and Codex metadata carry those skip cases because skill metadata is the host-visible routing boundary before the full workflow body is loaded.
|
||||
|
||||
Truth Sync delegation is host-owned. Generated workflow surfaces may describe when delegation is allowed, but must not name a preferred subagent or project-local subagent preference file.
|
||||
Truth Sync delegation is host-owned. Generated workflow surfaces may describe when delegation is allowed, but must not create unrestricted writable helpers or a project-local subagent preference file. Codex, Claude Code, GitHub Copilot, and OpenCode generated surfaces may name project-scoped read-only verifier agents for workflow-owned automatic verification and `truth-doc-writer` for leased truth-doc shards. Read-only verifier agents inspect only the parent-assigned shard plus required checkout evidence files and do not preload repo-wide instruction or policy docs unless the parent assigns those files as evidence. The parent workflow creates each lease, requires allowedWrites and forbiddenWrites, validates the actual checkout diff against the lease, and owns repo-policy interpretation and final acceptance.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
@@ -69,16 +72,18 @@ Truth Sync delegation is host-owned. Generated workflow surfaces may describe wh
|
||||
- Decision (2026-05-15): Truth Sync must not worsen weak topology by adding generic truth docs behind missing, stale, broad, overloaded, catch-all, or unrouteable routing.
|
||||
- Decision (2026-05-15): Truth Sync must switch to Truth Structure or block when impacted truth docs are mixed-owner or broad.
|
||||
- Decision (2026-05-15): Truth Sync must not lose Product Decisions or Rationale during bounded shape repair or inline Structure handoff.
|
||||
- Decision (2026-05-16): Codex, Claude Code, GitHub Copilot, and OpenCode subagents may automatically gather bounded read-only route and claim evidence for Sync when host-supported without preloading repo-wide policy by default. Sync may also dispatch `truth-doc-writer` only with an explicit write lease, while parent agents retain policy, acceptance, and diff-validation ownership.
|
||||
- Decision (2026-05-16): Truth Sync write authority is bounded by file class and route ownership, not by the root route index alone. It may write canonical truth docs and truth routing files, while functional code remains outside Sync authority.
|
||||
|
||||
## Rationale
|
||||
|
||||
Truth Sync is the finish-time bridge from code to truth, so it must protect route ownership before claim evidence. Otherwise it can accurately document behavior in the wrong place.
|
||||
Truth Sync is the finish-time bridge from code to truth, so it must protect route ownership before claim evidence. Otherwise it can accurately document behavior in the wrong place. Routing repair can require child route-file edits as well as root index edits, so Sync's safe boundary is leased truth routing files rather than one hard-coded route file.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no functional-code rewrites during sync
|
||||
- no generic docs behind weak routing
|
||||
- no preferred subagent baked into generated surfaces
|
||||
- no unleased writable subagent ownership baked into generated surfaces
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-14
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../README.md
|
||||
- ../ai/repo-rules.md
|
||||
@@ -75,7 +75,7 @@ Code surface:
|
||||
- src/realize/**
|
||||
- src/sync/**
|
||||
- src/templates/agents-block.ts
|
||||
- src/templates/codex-skills.ts
|
||||
- src/templates/workflow-surfaces.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/truth/**
|
||||
- src/version.ts
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-15
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
@@ -13,6 +13,7 @@ source_of_truth:
|
||||
## Installed Workflows
|
||||
|
||||
Truth documents:
|
||||
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/contracts.md
|
||||
@@ -27,6 +28,8 @@ truth_documents:
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-sync.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-preview.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-realize.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-check.md
|
||||
@@ -36,17 +39,19 @@ truth_documents:
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/agents/**
|
||||
- src/generation/**
|
||||
- src/realize/**
|
||||
- src/sync/**
|
||||
|
||||
- src/agents/\*\*
|
||||
- src/generation/\*\*
|
||||
- src/realize/\*\*
|
||||
- src/sync/\*\*
|
||||
- src/templates/agents-block.ts
|
||||
- src/templates/codex-skills.ts
|
||||
- src/templates/workflow-surfaces.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/truth/**
|
||||
- src/truth/\*\*
|
||||
- src/version.ts
|
||||
|
||||
Update truth when:
|
||||
|
||||
- installed workflow boundaries or report shapes change
|
||||
- generated instruction block or skill content changes
|
||||
- workflow version markers or sync classification behavior changes
|
||||
|
||||
Reference in New Issue
Block a user