Changes

The traceability grammar was inherited from presets and accreted by hand instead of being derived from the questions the workflow must answer. OpenSpec’s workflow shape is the reference model, but its store and engine cannot reach antora-tracer, so the workflow is rebuilt tracer-native. Four decisions settle the grammar. The change is the entry point and the requirement is the spec unit; both belong to the Tier-1 core. Scenarios remain prose inside a requirement, and a test verifies the requirement. Design is recorded as decisions rather than ADRs because most choices are domain or specification clarifications, not architecture. An approved requirement is immutable: a change to its meaning supersedes it with a new requirement. The workflow mechanics follow from the grammar: stage skills orchestrate the change lifecycle, a human acceptance gate plus validation enforces review before implementation, and only execution tasks are temporary.

The grammar is a three-tier model that starts lean and grows on demand. Tier 1, the workflow core, holds the change role with states proposed, refined, accepted, implemented, verified, closed, and rejected, and the requirement role with states draft, reviewed, approved, superseded, and withdrawn. Tier 2, understanding, holds the decision role with states proposed, accepted, rejected, and superseded, and the test role without a lifecycle. Tier 2 also holds growth roles that never gate the workflow: design_concept, use_case, goal, scenario, and arc42. Tier 3 holds temporary execution tasks as Markdown under tspec/, never in the graph. Initial relation pairs are change addresses requirement (reverse addressed_by), change records decision (reverse recorded_by), requirement supersedes requirement (reverse superseded_by), and test verifies requirement (reverse verified_by); either name may be authored and the edge canonicalizes to the primary direction. Initial matrices are changes-to-requirements and requirements-tests. A change carries structured rationale, outcome, and out-of-scope fields. A change cannot reach accepted without addressing at least one requirement. The grammar extends the minimal preset and declares change and decision instead of extending requirements-engineering. Six skills implement the workflow: explore, propose, apply, archive, and validate orchestrate the change lifecycle, and write-item creates items of any declared role. Propose writes the change, its requirements, and its decisions atomically so relation macros never dangle. A change is accepted by a human gate: the agent advances refined to accepted only on the human’s instruction, and validation enforces the transition. The temporary store is tspec/<change-id>/tasks.md, created by propose, consumed by apply, and deleted by archive. The command-line tool is thin: init scaffolds the project and installs the skills, no command drives the workflow, and validation and matrices stay with the antora-tracer CLI. An item is an anchor block [#ID, item, role=<role>, status=<state>, title="…​"] opening a -- delimited body of prose, relation macros, and a closing tracer:links[]. A relation macro is <relation>:<ID>[] written in the source item. A change body carries Rationale, Outcome, and Out-of-scope labeled-list fields. The changes-to-requirements matrix uses change rows, requirement columns, and the addresses coverage relation, and the requirements-tests matrix from the minimal preset uses requirement rows, test columns, and the verified_by and covers coverage relations. Explore reads code and produces a change sketch without writing. Apply ticks the tasks, adds test evidence, and advances the change from accepted to implemented to verified. Archive runs validation, deletes the tspec directory, and advances the change from verified to closed. Validate runs the antora-tracer check without changing state. Write-item writes one item of any declared role and wires its relations.

The implementation reset of the example content to the new grammar. Field-level enforcement and matrix presentation details. The skip-specs escape for requirement-free changes is not yet enforced.

The tspec skills must resolve item fields from role guidance, but antora-tracer role-guidance <role> --config traceability.yml --content fails today. The roleGuidance.*.page values are Antora-relative paths, but the tracer resolves them as filesystem paths relative to the config file, so guidance/change.adoc resolves to a nonexistent repo-root file instead of docs/modules/specs/pages/guidance/change.adoc. The guidance pages also carry no item template, so field names exist only as informal prose.

antora-tracer role-guidance change --config traceability.yml --content and its decision equivalent return their guidance pages, each carrying an Item template block that enumerates the role’s labeled-list fields.

The skill update that consumes the templates is a later change. Core-repo preset consistency is a separate change in the core repository. Roles, relations, workflow, and validation are unchanged.

tspec-archive closes a change after only structural validation (antora-tracer validate), which checks roles, relations, statuses, and dangling references but cannot catch conformance gaps. A requirement can be satisfied on paper yet not in the repository, such as a field named differently than the change declared or a page path that does not resolve. Conformance verification is currently ad hoc, so a change can reach closed with no independent check that the implementation satisfies its requirements. Verification has no standalone lifecycle: it only ever precedes close, so it belongs inside archive, not in a seventh skill.

tspec-archive runs an independent, read-only conformance review before advancing a change to closed. A cold reviewer reads the change, its addressed requirements, and its recorded decisions, checks each requirement against the repository state, and emits a per-requirement verdict. Archive closes only on a clean verdict.

A dedicated tspec-verify-change skill. New states or transitions: verified to closed is unchanged, and the gate is archive behavior, not a new state-machine rule. tspec-validate stays structural-only, and tspec-apply still self-advances to verified.

The decision role records only context, the chosen option, and consequences, so a reader cannot reconstruct what alternatives were weighed or why the chosen option won. MADR (Markdown Any Decision Records) provides a proven body structure — considered options with per-option pros and cons, the chosen option, and the rationale — that generalizes to any decision, not architecture. Adopt MADR’s body fields as an AsciiDoc labeled-list template; keep the Status, Deciders, Date, and Technical Story header out because the item’s status attribute, its recorded_by relation, and git already express them.

The decision guidance template declares MADR-shaped fields: Context, Options (with per-option good/bad nested), Decision, Rationale, and Consequences. Future decisions record the alternatives weighed, the one chosen, why it won, and the resulting trade-offs.

Markdown files. The core repository’s adr.adoc. Rewriting the existing DEC-001 to DEC-006 items, which stay as historical records. A Drivers field, deferred until decisions need an explicit force list.

The workflow describes a change in the traceability graph, but backlog, assignment, priority, and reporting live in an issue tracker such as Jira or GitHub. Today the only glue is a human pasting a tracker URL into a change’s prose, so the spec graph and the board drift apart. Projects need a stable pointer between a change and its tracker issue, a configurable declaration of where that tracker lives, and thin skills to move issues at lifecycle boundaries.

A tracer-spec-owned configuration file tspec.yml declares an optional tracker (provider none by default, plus github and jira, with reachability and an optional status map). A trackerId attribute on the change item block header is the stable pointer to the tracker issue, with no change to the traceability grammar. One tspec-track skill links or creates an issue when a change is proposed, imports a tracker-first issue as a seeded change, and pushes status at accepted, implemented, and closed transitions — always one-way, never reconciling tracker state back into the graph.

Bidirectional synchronization. Webhooks. Comment mirroring. Any provider beyond GitHub and Jira.

The propose skill says requirements "state WHAT, never how", but the rule is advisory and nothing forces a pause, so requirements get written with implementation nouns — for example "as a trackerId attribute on the change item block header". The requirement guidance already carries a "Solution prescription" flag list, but the skill never applies it.

The propose skill’s Rules gain a concrete gate: before writing each requirement, run the SHALL against the requirement guidance’s "Solution prescription" list, strip any mechanism to the observable outcome, and record the mechanism as a decision instead. The skill references the guidance’s flag list rather than duplicating it.

Automatic enforcement via validation or lint — the distinction is semantic and un-lintable. A new review skill. Changes to the human accept gate or the archive cold reviewer.

The site explains the workflow and shows its own traceability, but the two things a new user operates — the tracer-spec CLI and the seven workflow skills — are documented only in README.md and the SKILL.md files, not in the site. The existing pages also violate the repo’s own Diátaxis rule (one page = one mode): getting-started.adoc links out to Reference, workflow/overview.adoc mixes explanation with instructions, and workflow/authoring.adoc duplicates the guidance/ templates. A seventh skill, tspec-track, was added without touching the README, which still says six.

A complete Diátaxis site: how-to/ (scaffold a project, drive the seven-skill workflow), reference/ (CLI, skills catalog, roles, config), and explanation/ (workflow rationale, traceability). The mixed-mode pages are re-homed — workflow/overview.adoc becomes explanation/workflow.adoc, workflow/authoring.adoc is folded into reference/roles.adoc — and the tutorial’s out-links are removed. guidance/change.adoc and guidance/decision.adoc stay in place because traceability.yml roleGuidance points at them. The README is corrected to name all seven skills. use-cases/ and design/ remain, empty, for growth-role documentation.

Populating use-cases/ and design/ with growth-role content. Splitting the workflow how-to into per-skill pages. Documenting the full antora-tracer CLI beyond validate (linked out to its own reference). Rewriting item content under changes/, requirements/, or decisions/.