mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
feat: add canonical agent workflow package (#19)
* feat: add Truth Sync intent checklist * feat: add canonical agent workflow package Add the .truthmark/agent canonical workflow package, convert duplicated host workflow bodies into adapter/expanded-adapter surfaces, and validate canonical/adapter freshness in Truthmark check. Refresh generated surfaces and package metadata for Truthmark 2.3.0, with OpenSpec tasks completed and release notes added. * fix: preserve native workflow skill packages * docs: record native skill package decision * fix: drop unused agent workflow package * chore: remove implemented OpenSpec docs * chore: release workflow fixes as 2.2.2 * fix: remove agent-visible version markers * fix: drop generated surface version markers * feat: capture decision context in Truth Sync --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
This commit is contained in:
Merlin's Cat
@@ -84,7 +84,7 @@ Verification:
|
||||
- `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 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 describe all release-worthy pending changes since the previous release tag, not only the package metadata edit or generated-surface 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`.
|
||||
|
||||
@@ -45,7 +45,7 @@ If a linked `truthmark` binary points at this checkout's `dist/main.js`, `truthm
|
||||
- Run `npm run dev -- check` when canonical docs, authority order, or areas routing changes.
|
||||
- Run `npm run check` before closing out broader code changes unless a narrower command is the only relevant one.
|
||||
- Run `npm run release:check` before publishing or handing off release-sensitive packaging changes.
|
||||
- Run `npm run dev -- init --json`, inspect generated version-marker diffs, and then run `npm run dev -- check` when the package version changes.
|
||||
- Run `npm run dev -- init --json`, inspect generated-surface diffs, and then run `npm run dev -- check` when generated surfaces are expected to refresh.
|
||||
|
||||
## Documentation-Only Changes
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ Do not load this standard for ordinary docs, workflow text, generated-surface, o
|
||||
|
||||
Choose Truthmark's own package version using Semantic Versioning 2.0.0. Normal committed versions use `MAJOR.MINOR.PATCH`.
|
||||
|
||||
`package.json` is the maintained version source. `package-lock.json` follows it. Generated version markers follow the package version only after `truthmark init` is rerun.
|
||||
`package.json` is the maintained version source. `package-lock.json` follows it. Generated workflow surfaces are refreshed by rendered-content comparison plus `truthmark init`; they do not carry package-version freshness markers.
|
||||
|
||||
This is an internal repository maintenance standard. It is not a user-facing feature, installed workflow feature, or generated workflow capability.
|
||||
|
||||
@@ -43,12 +43,12 @@ No bump examples:
|
||||
|
||||
## Decision Table
|
||||
|
||||
| Change | Version action |
|
||||
| --- | --- |
|
||||
| Backward-incompatible public API or shipped workflow change | `MAJOR + 1`, reset `MINOR` and `PATCH` to `0` |
|
||||
| Backward-compatible public API addition, generated-surface capability, shipped workflow capability, deprecation, or substantial user-visible improvement | `MINOR + 1`, reset `PATCH` to `0` |
|
||||
| Backward-compatible bug fix, diagnostic correction, packaging fix, or published documentation correction | `PATCH + 1` |
|
||||
| Internal-only maintenance with no published package behavior change | no version change |
|
||||
| Change | Version action |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
|
||||
| Backward-incompatible public API or shipped workflow change | `MAJOR + 1`, reset `MINOR` and `PATCH` to `0` |
|
||||
| Backward-compatible public API addition, generated-surface capability, shipped workflow capability, deprecation, or substantial user-visible improvement | `MINOR + 1`, reset `PATCH` to `0` |
|
||||
| Backward-compatible bug fix, diagnostic correction, packaging fix, or published documentation correction | `PATCH + 1` |
|
||||
| Internal-only maintenance with no published package behavior change | no version change |
|
||||
|
||||
Do not use prerelease or build metadata in the committed package version unless the release task explicitly asks for it.
|
||||
|
||||
@@ -58,7 +58,7 @@ Treat these as published package behavior:
|
||||
|
||||
- CLI command names, options, exit behavior, result envelopes, and diagnostics contracts
|
||||
- `.truthmark/config.yml` schema and hierarchy behavior
|
||||
- generated instruction blocks, skill metadata, prompt files, and version markers produced by the package
|
||||
- generated instruction blocks, skill metadata, prompt files, helper manifests, and managed refresh markers produced by the package
|
||||
- installed workflow boundaries, trigger contracts, report shapes, and completion gates as shipped package behavior
|
||||
- runtime compatibility and npm package contents
|
||||
|
||||
@@ -76,7 +76,7 @@ When changing a version number:
|
||||
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.
|
||||
4. Rerun `truthmark init` when generated surfaces need refresh, then inspect the generated-surface diffs. Generated surfaces use managed/stale-surface wording instead of package-version freshness markers; helper manifests name the runner and command shape without pinning the package version.
|
||||
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.
|
||||
|
||||
## Agent Output
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-14
|
||||
last_reviewed: 2026-06-17
|
||||
---
|
||||
|
||||
# Init And Scaffold
|
||||
@@ -18,7 +18,7 @@ It covers config defaults, lane root creation, template files, and starter route
|
||||
|
||||
Defaults derive all scaffold paths from `truthmark.workspace`. Routes are fixed at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`; the default scaffolded route area is `repository`; max route delegation depth is `1`; product truth is fixed at `<workspace>/product`; engineering truth is fixed at `<workspace>/engineering`; editable truth templates are fixed at `<workspace>/templates`. Template filenames match `truth_kind` values directly: `product-capability.md`, `engineering-behavior.md`, `engineering-contract.md`, `engineering-architecture.md`, `engineering-workflow.md`, `engineering-operations.md`, and `engineering-test-behavior.md`. Generated truth-doc frontmatter includes `truth_kind` and does not include `doc_type` or `truth_lane`.
|
||||
|
||||
Init reads the default seeded behavior leaf from `engineering-behavior.md`. Downstream product truth uses the `product-capability` template only. Capability docs own a single user-visible capability promise, users/value, scope including boundary constraints and adjacent systems, current product behavior, acceptance criteria, decisions, realization links, and non-goals.
|
||||
Init seeds the broad default `repository` route as provisional bootstrap routing, not as normal behavior ownership. The route still maps `src/**` so a fresh repository is routeable, but it points at `engineering/repository/bootstrap-routing.md` as an `engineering-workflow` handoff that tells agents to run Truth Structure before normal Truth Sync when real code touches only the broad default route. Init does not create `engineering/repository/overview.md` from `engineering-behavior.md`; behavior truth should be created in bounded areas after ownership is known. Downstream product truth uses the `product-capability` template only. Capability docs own a single user-visible capability promise, users/value, scope including boundary constraints and adjacent systems, current product behavior, acceptance criteria, decisions, realization links, and non-goals.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
@@ -29,6 +29,7 @@ Init reads the default seeded behavior leaf from `engineering-behavior.md`. Down
|
||||
- Decision (2026-06-14): New scaffold targets do not create `docs/truthmark/truth` as the canonical target root.
|
||||
- Decision (2026-06-14): Editable template filenames match `truth_kind` values directly so generated docs do not point agents at legacy `*-doc.md` names.
|
||||
- Decision (2026-06-14): Init scaffolds routes, templates, product truth, and engineering truth at fixed workspace-derived paths rather than accepting route or template roots from config.
|
||||
- Decision (2026-06-17): The default broad `repository` route is provisional bootstrap state; init creates a compact `bootstrap-routing.md` workflow handoff instead of a catch-all behavior overview so agents run Truth Structure before normal Sync on real touched code.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
@@ -36,9 +37,9 @@ Update when init writes new files, changes default paths, changes template filen
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../../../src/config/defaults.ts
|
||||
- ../../../../src/init/hierarchy.ts
|
||||
- ../../../../src/templates/init-files.ts
|
||||
- ../../../../src/config/defaults.ts
|
||||
- `src/config/defaults.ts`
|
||||
- `src/init/hierarchy.ts`
|
||||
- `src/templates/init-files.ts`
|
||||
- ../../../../tests/init/init-instructions.test.ts
|
||||
- ../../../../tests/templates/init-files.test.ts
|
||||
- ../../../../tests/integration/init-check-workflow.test.ts
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-contract
|
||||
last_reviewed: 2026-06-15
|
||||
last_reviewed: 2026-06-17
|
||||
---
|
||||
|
||||
# Config, Route, And Check Contracts
|
||||
@@ -16,7 +16,7 @@ It covers config normalization, route `truth_documents` metadata, diagnostic cat
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
Default config exposes `truthmark.workspace` and `truthmark.generated.portal.enabled`; it does not expose route layout, template layout, or truth lane roots as knobs. Routes are fixed at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`, the default area is the product invariant `repository`, max delegation depth is the product invariant `1`, templates are fixed at `<workspace>/templates`, product truth is fixed at `<workspace>/product`, and engineering truth is fixed at `<workspace>/engineering`. User-provided `truthmark.routes`, `truthmark.templates`, or `truthmark.truth` blocks are rejected as unsupported additional properties. Route entries can declare `kind`, optional `lane`, `realized_by`, `realizes`, and `depends_on`; product `realized_by` and engineering `realizes` links are valid when their targets exist and point to the opposite lane, without requiring reciprocal declarations. Duplicate route entries for the same path, kind, and lane merge relationship metadata for `realized_by`, `realizes`, and `depends_on` by unique sorted set before validation and RouteMap output; conflicting duplicate kinds or lanes are reported as area-index errors. The public ContextPack command surface is retired. Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for workflow applicability, write boundaries, target truth docs, checks, helper commands, diagnostics, next steps, and compact affected-test guidance, and `truthmark impact --base <ref> --json` for branch-diff routing. These replacement JSON outputs emit paths, metadata, diagnostics, and command arrays only; they do not embed source-file or truth-doc body contents.
|
||||
Default config exposes `truthmark.workspace` and `truthmark.generated.portal.enabled`; it does not expose route layout, template layout, or truth lane roots as knobs. Routes are fixed at `<workspace>/routes/areas.md` and `<workspace>/routes/areas/`, the default area is the product invariant `repository`, max delegation depth is the product invariant `1`, templates are fixed at `<workspace>/templates`, product truth is fixed at `<workspace>/product`, and engineering truth is fixed at `<workspace>/engineering`. User-provided `truthmark.routes`, `truthmark.templates`, or `truthmark.truth` blocks are rejected as unsupported additional properties. Route entries can declare `kind`, optional `lane`, `realized_by`, `realizes`, and `depends_on`; product `realized_by` and engineering `realizes` links are valid when their targets exist and point to the opposite lane, without requiring reciprocal declarations. Duplicate route entries for the same path, kind, and lane merge relationship metadata for `realized_by`, `realizes`, and `depends_on` by unique sorted set before validation and RouteMap output; conflicting duplicate kinds or lanes are reported as area-index errors. The public ContextPack command surface is retired. Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for an advisory workflow card, write-boundary suggestions, suggested truth docs, review checklist, evidence prompts, optional helper commands, open questions, skipped-helper status, diagnostics, next steps, and compact affected-test guidance, and `truthmark impact --base <ref> --json` for branch-diff routing. These replacement JSON outputs emit paths, metadata, diagnostics, and command arrays only; they do not embed source-file or truth-doc body contents.
|
||||
|
||||
## Contract Surface
|
||||
|
||||
@@ -69,6 +69,9 @@ Update when config fields, route metadata, diagnostics, route/index output schem
|
||||
- ../../../../src/config/load.ts
|
||||
- ../../../../src/routing/areas.ts
|
||||
- ../../../../src/output/diagnostic.ts
|
||||
- ../../../../src/workflow-state/types.ts
|
||||
- ../../../../src/workflow-state/build.ts
|
||||
- ../../../../tests/cli/index-impact-context.test.ts
|
||||
- `src/config/schema.ts`
|
||||
- `src/routing/areas.ts`
|
||||
- `src/repo-index/types.ts`
|
||||
|
||||
@@ -33,7 +33,7 @@ Truthmark renders workflow surfaces for configured platforms and leaves already
|
||||
|
||||
- Host-native workflow skill packages and compact prompt/command adapters
|
||||
- Optional helper manifests
|
||||
- Managed instruction blocks with the Truthmark version marker
|
||||
- Managed instruction blocks with non-versioned refresh guidance
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-17
|
||||
---
|
||||
|
||||
# Repository Bootstrap Routing
|
||||
|
||||
## Purpose
|
||||
|
||||
This doc records the provisional broad route for repository.
|
||||
This doc is a bootstrap handoff, not a behavior truth dumping ground.
|
||||
It is not a substitute for bounded product and engineering truth docs.
|
||||
|
||||
## Scope
|
||||
|
||||
This doc owns only the initial routing workflow for a fresh Truthmark repository whose default route still maps a broad code surface such as `src/**`.
|
||||
It does not own implementation behavior under that code surface.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
The scaffold creates this provisional bootstrap handoff only when a default broad route needs a canonical owner. Agents use it as a signal to run Truth Structure and create bounded routes before normal Truth Sync, not as a place to accumulate implementation claims.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- None. This is an engineering bootstrap handoff for routing setup, not a product promise.
|
||||
|
||||
## Triggers
|
||||
|
||||
- A real code change maps only to this provisional broad route.
|
||||
- Truth Sync cannot identify a specific behavior-owned route and bounded truth owner.
|
||||
- A maintainer or agent is onboarding the first real product, service, domain, package, or ownership area.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Current route files under the configured Truthmark route root.
|
||||
- The touched code, tests, configuration, and existing docs needed to infer the smallest real owner.
|
||||
- Repository instruction files that exist in the checkout.
|
||||
|
||||
## Execution Model
|
||||
|
||||
Run Truth Structure before normal Truth Sync when real code changes touch only this broad route. Truth Structure should create or repair bounded areas first; Truth Sync should then update the bounded owner docs.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Treat this route as provisional and insufficient for normal behavior maintenance.
|
||||
2. Inspect the touched code/test surface and infer the narrowest durable owner.
|
||||
3. Create or repair route entries and truth docs for that owner.
|
||||
4. Leave this bootstrap doc small; do not append behavior details here.
|
||||
5. Resume Truth Sync only after the touched code resolves to a bounded owner.
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
If ownership cannot be inferred safely, stop and report manual-review files instead of widening this route or adding generic behavior prose.
|
||||
|
||||
## Outputs
|
||||
|
||||
- Bounded route areas and lane-appropriate truth docs for the touched surface.
|
||||
- A compact manual handoff report when ownership remains ambiguous.
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
- Decision (2026-06-17): Default broad routing is provisional bootstrap state. Agents should create bounded areas before normal Truth Sync rather than extending a catch-all overview doc.
|
||||
|
||||
## Rationale
|
||||
|
||||
Scoped ownership keeps agent context close to affected files and prevents broad default docs from absorbing unrelated behavior. This preserves agent-native truth maintenance without adding a token-heavy discovery layer.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc is not a repository behavior overview.
|
||||
- This doc is not a product capability or engineering behavior owner.
|
||||
- This doc is not a permanent home for claims about files under `src/**`.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Keep this doc short. When a repository has real bounded routes, prefer updating those routes and their truth docs instead of expanding this bootstrap handoff.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../routes/areas/repository.md
|
||||
- ../../../../.truthmark/config.yml
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-16
|
||||
last_reviewed: 2026-06-17
|
||||
---
|
||||
|
||||
# Repository Intelligence
|
||||
@@ -22,10 +22,12 @@ Repository intelligence is language-neutral workflow context, not a language-sem
|
||||
|
||||
ImpactSet remains the branch-diff routing handoff for changed files, affected routes, affected truth docs, affected tests, and diagnostics. It derives affected routes from route code surfaces and truth-doc ownership, derives affected tests from changed test paths and path/name hints, and reports diagnostics for unmapped functional-code changes. It does not report TypeScript public-symbol changes or use TypeScript/JavaScript import parsing to infer affected tests.
|
||||
|
||||
WorkflowState is the workflow-scoped handoff for applicability, action context, write boundaries, target truth docs, helper validation commands, checks, compact affected-test guidance, diagnostics, next steps, and report sections. `truthmark-sync` keeps affected truth docs in `targetTruthDocs` for review focus, while its write context intentionally authorizes indexed canonical truth docs and truth routing files so Sync can correct stale repository truth beyond the initially affected route when evidence supports it. The standalone ContextPack handoff is retired; agents use workflow status plus impact instead. These outputs do not emit source-file or truth-doc body contents.
|
||||
WorkflowState is the workflow-scoped advisory handoff for helper readiness, a workflow card, write-boundary suggestions, target truth docs, optional helper commands, review checklist, compact affected-test guidance, diagnostics, next steps, and report sections. The advisory card presents affected files, likely route owners, suggested truth docs, open questions, and skipped optional-helper status so helper output remains review material rather than repository authority. Workflow applicability uses context-shaped states such as `ready`, `needs_manual_review`, and `needs_routing_review`; diagnostics or missing route ownership produce open questions and manual handoff guidance instead of making the CLI the arbiter. `truthmark-sync` includes `Sync Intent` in its report sections as a transient pre-write checklist and keeps affected truth docs in `targetTruthDocs` for review focus. Sync action context separates `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles`: agents start with impacted route owners, while indexed canonical truth docs outside the impact set remain candidate stale-truth repair targets that require checkout evidence and a recorded reason before being touched. The standalone ContextPack handoff is retired; agents use workflow status plus impact as optional guidance and continue with direct checkout inspection when helpers are skipped or unavailable. These outputs do not emit source-file or truth-doc body contents.
|
||||
|
||||
Evidence validation checks repository containment, referenced file or glob existence, line spans, and `sha256:` content hashes. Evidence `symbol` metadata, when present in an evidence YAML block, is non-normative metadata and is not validated through TypeScript-specific parsing.
|
||||
|
||||
Generated-surface diagnostics are checkout-derived repository intelligence for the installed workflow runtime. `truthmark check` compares rendered generated surfaces with committed files and reports missing or stale generated host-native skill package files so skill-directory resources stay colocated with `SKILL.md`.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- `docs/truthmark/product/capabilities/lane-separated-truth.md`
|
||||
@@ -34,8 +36,11 @@ Evidence validation checks repository containment, referenced file or glob exist
|
||||
|
||||
- Decision (2026-06-14): Repository intelligence is derived context, not hidden memory or off-repo authority.
|
||||
- Decision (2026-06-15): Repository intelligence is a language-neutral workflow helper, not a semantic code index; TypeScript-specific import/export/public-symbol analysis is not part of the public contract.
|
||||
- Decision (2026-06-15): The standalone ContextPack handoff is retired; agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for workflow-scoped guidance and `truthmark impact --base <ref> --json` for branch-diff routing.
|
||||
- Decision (2026-06-16): Truth Sync write context is broad across indexed canonical truth docs and truth routing files; `targetTruthDocs` remains the affected-doc focus list, not the full write lease.
|
||||
- Decision (2026-06-15): The standalone ContextPack handoff is retired; agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for optional workflow-scoped guidance and `truthmark impact --base <ref> --json` for branch-diff routing.
|
||||
- Decision (2026-06-16): `workflow status` is status/debug/handoff only; Truthmark does not expose a `workflow instructions` command and generated workflows must remain usable from committed repository files without live CLI preflight.
|
||||
- Decision (2026-06-17): WorkflowState presents optional helper output as an advisory workflow card with affected files, likely route owners, suggested truth docs, open questions, skipped helper status, `reviewChecklist`, and `evidencePrompts`; it does not expose retired enforcement-shaped names such as `checks.required`, the old gate alias, or `requiredEvidence`.
|
||||
- Decision (2026-06-16): Sync Intent is a transient report-section checklist exposed through workflow/report surfaces and WorkflowState report sections; it is not repository-intelligence state or a persisted plan.
|
||||
- Decision (2026-06-17): Generated-surface freshness includes host-native package diagnostics; these diagnostics are review output and do not add hooks, live services, duplicate workflow packages, or mandatory workflow preflight execution.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
@@ -50,7 +55,11 @@ Update when index, route-map, impact, evidence, freshness, or workflow-state out
|
||||
- ../../../../src/impact/build.ts
|
||||
- ../../../../src/impact/types.ts
|
||||
- ../../../../src/evidence/validate.ts
|
||||
- ../../../../src/workflow-state/action-context.ts
|
||||
- ../../../../src/workflow-state/build.ts
|
||||
- ../../../../src/workflow-state/types.ts
|
||||
- ../../../../src/checks/generated-surfaces.ts
|
||||
- ../../../../tests/workflow-state/build.test.ts
|
||||
- `src/repo-index/build.ts`
|
||||
- `src/repo-index/file-tree.ts`
|
||||
- `src/repo-index/route-map.ts`
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-16
|
||||
last_reviewed: 2026-06-17
|
||||
---
|
||||
|
||||
# Installed Workflow Runtime
|
||||
@@ -16,7 +16,9 @@ It owns generated workflow runtime behavior, managed instruction blocks, helper
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
The source manifest and renderers generate host-specific skills, prompts, commands, subagents, helper manifests, and managed instruction blocks. Generated skill packages hold the full workflow procedures and report contracts. Generated GitHub Copilot prompts and Gemini commands act as compact host entrypoint adapters: they direct the current invocation to host-local skill package files and explicitly avoid dispatching another Truthmark command rather than embedding duplicate workflow bodies or cross-host invocation lists. Generated write-capable workflow text instructs agents to classify lane impact before writing canonical truth docs, while read-only Preview and Check surfaces classify lane ownership for reporting without write-authorizing phrasing. The manual Truth Realize prompt path uses Realize-specific lane guidance: read product truth as requirements, read engineering truth as implementation context, and do not write truth docs or truth routing while realizing docs into code. Truth Preview keeps route selection thin by reading the root route index first and then only child route files relevant to the selected scope or changed paths. Truth Check and read-only route auditors use route-first bounded inspection for lane and cross-lane relationship checks: narrow audits stay within the routed area plus directly linked counterpart docs, root-wide health first builds a route-map/index from route files, and missing product links for user-visible engineering docs are second-pass review diagnostics rather than default full-document reads. Optional CLI repository-intelligence helpers are compact: workflow status exposes WorkflowState/action context, and impact exposes branch-diff routing data; neither helper emits source-file or truth-doc body contents. Truth Sync workflow status intentionally exposes broad write paths for indexed canonical truth docs and truth routing files so the workflow can correct stale repository truth across the checkout when supported by evidence.
|
||||
The source manifest and renderers are the package-generation authority; `truthmark init` projects that source into host-native workflow files. Generated host skill directories are native skill packages: their `SKILL.md` files keep package-local `support/procedure.md`, `support/report-template.md`, subagent/lease guidance, helper manifests, and helper policy files so hosts that package skill-directory resources do not depend on arbitrary cross-repository file reads. Truthmark does not emit a separate `.truthmark/agent/` workflow copy because host skill packages are the runtime surfaces agents actually load; duplicating them under `.truthmark/agent/` would add repository docs with no active host consumer. GitHub Copilot prompts, Gemini commands, and top-level managed instruction blocks stay thin and point to host-native workflow entrypoints rather than embedding full workflow bodies. Generated-surface checks report missing or stale host-native skill package files.
|
||||
|
||||
Workflow manifest entries use review-oriented questions that surface as a WorkflowState `reviewChecklist`, while evidence-oriented entries surface as `evidencePrompts`. Generated GitHub Copilot prompts and Gemini commands act as compact host entrypoint adapters: they direct the current invocation to host-local skill package files and explicitly avoid dispatching another Truthmark command rather than embedding duplicate workflow bodies or cross-host invocation lists. Truth Sync generated procedures use a product-truth decision before canonical truth writes: update or route product truth only when a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed; otherwise internal implementation changes default to engineering truth. Truth Sync also performs decision context capture from the current task conversation: agents review user-provided decisions, rationale, constraints, tradeoffs, rejection reasons, and scope boundaries, carry that context into Sync Intent, place it in the correct product or engineering truth lane when supported, and report whether it was placed, skipped because none was provided, or needs manual handoff. Other write-capable truth workflows preserve lane-specific classification before canonical truth writes, while read-only Preview and Check surfaces classify lane ownership for reporting without write-authorizing phrasing. The manual Truth Realize prompt path uses Realize-specific lane guidance: read product truth as requirements, read engineering truth as implementation context, and do not write truth docs or truth routing while realizing docs into code. Truth Preview keeps route selection thin by reading the root route index first and then only child route files relevant to the selected scope or changed paths, and reports unresolved manual handoff questions rather than final correctness. Truth Check and read-only route auditors use route-first bounded inspection for lane and cross-lane relationship checks: narrow audits stay within the routed area plus directly linked counterpart docs, root-wide health first builds a route-map/index from route files, and missing product links for user-visible engineering docs are second-pass review diagnostics rather than default full-document reads. Truth Sync generated procedures and report templates include a transient Sync Intent checkpoint that records changed code reviewed, affected route/truth owner, target truth docs, intended update, evidence to verify, user-provided decisions/rationale, no-update-needed rationale, and blockers before canonical truth writes. Optional CLI repository-intelligence helpers are compact advisory cards: workflow status reports affected files, likely route owners, suggested truth docs, open questions, skipped helper status, and compact write-boundary suggestions; impact exposes branch-diff routing data; neither helper emits source-file or truth-doc body contents. Truth Sync workflow status separates impacted primary truth docs from candidate stale truth docs and route files so stale repository-truth correction remains available without making every indexed doc look like the starting scope.
|
||||
|
||||
## Triggers
|
||||
|
||||
@@ -34,9 +36,14 @@ Committed workflow files are the runtime contract. The CLI installs and validate
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
- Decision (2026-06-14): Lane classification is part of generated workflow text before any canonical truth write.
|
||||
- Decision (2026-06-14): Product and engineering truth remain separate generated-workflow lanes for truth creation, structure, audit, and cross-lane ownership checks.
|
||||
- Decision (2026-06-17): Routine code-first Truth Sync uses a product-truth decision instead of a full lane-classification gate; product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
|
||||
- Decision (2026-06-15): Optional workflow handoff helpers use `workflow status --json` and `impact --json`; generated surfaces must not direct agents to a standalone ContextPack command.
|
||||
- Decision (2026-06-16): Truth Sync status may authorize indexed canonical truth docs and truth routing files broadly; changed-file impact still controls applicability and focus, not the full write scope.
|
||||
- Decision (2026-06-16): `truthmark workflow instructions` is intentionally absent; committed host-native workflow files and direct checkout inspection are the runtime contract, while `workflow status` remains an optional compact helper.
|
||||
- Decision (2026-06-17): Workflow status presents optional helper output as advisory workflow cards with review checklists, evidence prompts, open questions, and skipped-helper status; generated workflows still run from committed host-native files and direct checkout inspection when helpers are unavailable.
|
||||
- Decision (2026-06-16): Truth Sync uses a transient Sync Intent checklist in generated procedures and report templates before truth writes; it is not a persistent plan object or lifecycle artifact.
|
||||
- Decision (2026-06-18): Truth Sync treats user-provided decision rationale from the current task conversation as first-class sync input. The workflow records that context in Sync Intent, routes it to the correct product or engineering truth section when supported, and reports where it was placed, skipped because none was provided, or handed off for manual review.
|
||||
- Decision (2026-06-17): Source manifest/renderers are the workflow-generation authority; configured host skill directories are native generated packages with colocated resources. Truthmark does not emit a separate `.truthmark/agent/` workflow copy when no host surface consumes it.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
@@ -47,8 +54,11 @@ Update this doc when workflow manifest fields, generated surface paths, helper m
|
||||
- ../../../../src/agents/instructions.ts
|
||||
- ../../../../src/agents/prompts.ts
|
||||
- ../../../../src/agents/workflow-manifest.ts
|
||||
- ../../../../src/agents/truth-sync.ts
|
||||
- ../../../../src/sync/report.ts
|
||||
- ../../../../src/templates/workflow-surfaces.ts
|
||||
- ../../../../src/templates/generated-surfaces.ts
|
||||
- ../../../../src/checks/generated-surfaces.ts
|
||||
- `src/agents/workflow-manifest.ts`
|
||||
- `src/templates/workflow-surfaces.ts`
|
||||
- `src/templates/generated-surfaces.ts`
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: product-capability
|
||||
last_reviewed: 2026-06-16
|
||||
last_reviewed: 2026-06-17
|
||||
---
|
||||
|
||||
# Agent-Native Workflow Injection
|
||||
@@ -20,19 +20,24 @@ This capability covers generated host-native workflow files, managed instruction
|
||||
|
||||
## Current Product Behavior
|
||||
|
||||
Supported surfaces include Codex, OpenCode, Claude Code, GitHub Copilot, and Gemini CLI workflow files generated from the source templates and manifest. Agents may use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` and `truthmark impact --base <ref> --json` as optional compact helpers for applicability, write boundaries, routing, affected tests, and diagnostics; these helpers do not provide file-content packets. Truth Sync status can authorize indexed canonical truth docs and truth routing files broadly so agents can correct stale repository truth beyond the initially affected documents when supported by checkout evidence.
|
||||
Supported surfaces include Codex, OpenCode, Claude Code, GitHub Copilot, and Gemini CLI workflow files generated from the source templates and manifest. Host skill directories are generated as native skill packages: `SKILL.md` plus colocated support files, helper manifests, helper policies, and subagent or lease guidance where the workflow uses them. Compact prompt, command, and top-level instruction surfaces may point into those host-native packages, but configured skill directories are not adapter-only pointer folders because some hosts package and progressively disclose resources from the skill directory itself. Truthmark does not add a separate `.truthmark/agent/` workflow copy unless a host surface actually consumes it; the checked-in host-native packages are the runtime workflow surfaces. Agents may use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` and `truthmark impact --base <ref> --json` as optional compact helpers for advisory workflow cards, affected files, likely route owners, suggested truth docs, review checklists, evidence prompts, open questions, skipped helper status, and diagnostics; these helpers do not provide file-content packets and are not sources of truth. Truth Sync status separates impacted `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles` so agents start with affected route owners while preserving evidence-backed stale repository-truth correction beyond the initially affected documents.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Each configured platform receives host-native workflow entrypoints.
|
||||
- Each configured host skill directory receives the workflow support files needed for native skill resource packaging.
|
||||
- Generated surfaces preserve workflow boundaries and direct-checkout fallback.
|
||||
- Agents can classify product-lane, engineering-lane, both-lane, or ambiguous work before writing truth docs.
|
||||
- Routine code-first Truth Sync defaults internal implementation changes to engineering truth unless a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed.
|
||||
- Truth Sync carries user-provided decision rationale, constraints, tradeoffs, rejection reasons, and scope boundaries from the current task conversation into Sync Intent, routes them to the correct truth lane when supported, and reports placement, skip, or manual handoff.
|
||||
- Workflows that create, structure, or audit truth docs still preserve product and engineering truth as separate lanes.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-06-14): Workflow surfaces remain committed repository files; optional CLI helpers validate after relevant work and do not orchestrate workflow execution.
|
||||
- Decision (2026-06-15): Agent-facing repository-intelligence handoff uses workflow status plus impact instead of a standalone ContextPack command.
|
||||
- Decision (2026-06-16): Truth Sync write authorization is broad across indexed repository truth surfaces; affected docs remain a focus signal rather than a write ceiling.
|
||||
- Decision (2026-06-17): Optional workflow status presents helper output as advisory workflow cards with review checklists, evidence prompts, open questions, and skipped-helper status; direct checkout inspection remains the fallback when helpers are skipped, unavailable, or unnecessary.
|
||||
- Decision (2026-06-17): Host skill directories are product-owned native packages, not adapter-only pointers. Justification: agent skill systems may discover and package the skill directory as the resource boundary, so `SKILL.md` must be colocated with procedure, report-template, helper, and lease resources needed for progressive disclosure. Compact adapters may point to host-native packages, but removing those colocated resources from configured skill folders would make workflow behavior depend on manual cross-repository reads and could fail in hosts or sandboxes that package only the skill directory. A separate `.truthmark/agent/` workflow copy is not generated unless a host surface actually consumes it, because otherwise it is duplicate repository documentation rather than runtime surface.
|
||||
- Decision (2026-06-18): Truth Sync exposes conversation-provided decision rationale as a visible workflow input and report outcome, without transcript ingestion, hidden memory, required hooks, persistent inbox files, mandatory ADRs, or extra proposal artifacts.
|
||||
|
||||
## Engineering Realization Links
|
||||
|
||||
|
||||
@@ -84,6 +84,7 @@ Code surface:
|
||||
- src/templates/agents-block.ts
|
||||
- src/templates/workflow-surfaces.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/checks/generated-surfaces.ts
|
||||
- src/truth/\*\*
|
||||
- src/version.ts
|
||||
- tests/evals/\*\*
|
||||
@@ -93,7 +94,7 @@ 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
|
||||
- generated-surface refresh markers or sync classification behavior changes
|
||||
|
||||
## Release Automation
|
||||
|
||||
|
||||
@@ -39,6 +39,7 @@ Code surface:
|
||||
- src/templates/agents-block.ts
|
||||
- src/templates/workflow-surfaces.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/checks/generated-surfaces.ts
|
||||
- src/truth/\*\*
|
||||
- src/version.ts
|
||||
- tests/evals/\*\*
|
||||
@@ -48,8 +49,9 @@ 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
|
||||
- ownership gates, evidence gates, lane classification gates, decision/rationale preservation gates, or truth-doc split behavior changes
|
||||
- host-native package mode, prompt/command adapter mode, or generated-surface freshness diagnostics change
|
||||
- generated-surface refresh markers or sync classification behavior changes
|
||||
- ownership reviews, evidence checklists, product-truth decisions, lane classification behavior, decision/rationale preservation reviews, or truth-doc split behavior changes
|
||||
|
||||
## Source References
|
||||
|
||||
|
||||
@@ -65,7 +65,7 @@ Distinguish validation errors, dependency failures, authorization failures, and
|
||||
|
||||
<!--
|
||||
State backward/forward compatibility guarantees, tolerated inputs, deprecation rules, and breaking-change triggers.
|
||||
Include compatibility tests or review gates that protect the contract.
|
||||
Include compatibility tests or review questions that protect the contract.
|
||||
-->
|
||||
|
||||
{{compatibility_rules}}
|
||||
|
||||
@@ -65,7 +65,7 @@ Include user-facing authorization behavior and operator access requirements when
|
||||
|
||||
<!--
|
||||
Describe deployment mechanism, migration ordering, compatibility windows, rollback path, and known irreversible operations.
|
||||
Call out manual gates, smoke checks, and post-deploy verification responsibilities.
|
||||
Call out manual review points, smoke checks, and post-deploy verification responsibilities.
|
||||
-->
|
||||
|
||||
{{deployment_and_rollback}}
|
||||
|
||||
@@ -47,7 +47,7 @@ Include validation, defaults, and normalization that happen before execution.
|
||||
|
||||
<!--
|
||||
Describe synchronous/asynchronous execution, concurrency, locking, leases, batching, ordering, and idempotency behavior.
|
||||
State whether the workflow is user-blocking, background, distributed, or delegated to another system.
|
||||
State whether the workflow waits for user action, runs in the background, is distributed, or is delegated to another system.
|
||||
-->
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
Reference in New Issue
Block a user