Components

<References refs="parser-pipeline/req" />
<TrackedFiles paths="crates/supersigil-core/src/component_defs.rs" />

Components are XML elements inside supersigil-xml fenced code blocks that carry specification semantics. Supersigil has 11 built-in components. Each component is validated during verification and becomes a typed node in the specification graph.

Caution

All component attributes must be plain double-quoted string literals. Use comma-separated strings for multi-value attributes: refs="doc-a#crit-1, doc-b#crit-2".

<AcceptanceCriteria>

Groups one or more <Criterion> components. Used for visual and semantic grouping.

<AcceptanceCriteria>
  <Criterion id="valid-input">...</Criterion>
  <Criterion id="invalid-input">...</Criterion>
</AcceptanceCriteria>

Attributes: None.

Not referenceable.

<Criterion>

A single verifiable criterion. This is the only “verifiable” component — the target of coverage tracking.

<Criterion id="valid-creds">
  WHEN a user submits valid credentials
  THE SYSTEM SHALL issue a session token within 200ms
</Criterion>

Attribute	Required	List	Description
id	yes	no	Unique identifier within the document. Referenced as doc-id#criterion-id

Referenceable. The missing_verification_evidence rule checks that every criterion has verification evidence pointing to it.

<References>

Informational traceability links. Creates edges in the graph for documentation purposes but has no verification semantics — it does not satisfy coverage.

<References refs="auth/req/login#valid-creds, auth/req/login#invalid-creds" />

Attribute	Required	List	Description
refs	yes	yes	Comma-separated document or criterion IDs

Not referenceable.

<VerifiedBy>

Specifies how a criterion is verified: by tag-based test matching or by file glob patterns.

<VerifiedBy strategy="tag" tag="test_login_success" />
<VerifiedBy strategy="file-glob" paths="tests/auth/test_session.rs" />

Attribute	Required	List	Description
strategy	yes	no	"tag" or "file-glob"
tag	if strategy=tag	no	Tag to search for in test files
paths	if strategy=file-glob	yes	File patterns matching test files

Strategies:

• tag — Searches test files for the comment // supersigil: {tag} (or # supersigil: {tag} for Python/shell). The format is fixed.
• file-glob — Matches test files by path glob. Simpler but less precise.

Not referenceable.

<Implements>

Declares that the containing document implements criteria from another document. Typically used by design documents pointing at requirements.

<Implements refs="auth/req/login#valid-creds" />

Attribute	Required	List	Description
refs	yes	yes	Comma-separated document or criterion IDs being implemented

Not referenceable.

<DependsOn>

Declares document-level dependencies. Used for dependency tracking and cycle detection.

<DependsOn refs="auth/design/session-mgmt, auth/req/login" />

Attribute	Required	List	Description
refs	yes	yes	Comma-separated document IDs this document depends on

Not referenceable.

<Task>

A trackable work item. Tasks live in documents with type: tasks.

<Task id="define-model" status="done" implements="auth/req/login#valid-creds">
  Define the user authentication data model.
</Task>

<Task id="add-validation" status="in-progress" depends="define-model">
  Add input validation for the login endpoint.
</Task>

Attribute	Required	List	Description
id	yes	no	Unique identifier within the document
status	no	no	Task status (e.g. draft, ready, in-progress, done)
implements	no	yes	Criteria this task implements (doc-id#criterion-id)
depends	no	yes	Task IDs this task depends on (within the same document)

Referenceable. Tasks form a dependency sub-graph within a document. depends edges are checked for cycles, and supersigil plan uses topological sort to determine implementation order.

<TrackedFiles>

Declares which source files this specification cares about. Used by supersigil affected for staleness detection.

<TrackedFiles paths="src/auth/**/*.rs, tests/auth/**/*.rs" />

Attribute	Required	List	Description
paths	yes	yes	File glob patterns to track

Not referenceable.

Note

<TrackedFiles> is a routing signal, not a correctness assertion. It flags the spec for review when matched files change — it does not verify that those files implement the spec.

<Decision>

A recorded architectural choice. Typically used in ADR documents. Can contain <Rationale>, <Alternative>, <References>, <TrackedFiles>, and <DependsOn> as children.

<Decision id="unidirectional-refs">
  References always point from concrete to abstract.

  <Rationale>
    Bidirectional references create synchronization burden.
  </Rationale>

  <Alternative id="bidirectional" status="rejected">
    Maintain forward and reverse refs in both documents.
  </Alternative>
</Decision>

Attribute	Required	List	Description
id	yes	no	Unique identifier within the document
standalone	no	no	Reason string declaring the decision is intentionally unconnected. Suppresses the orphan_decision rule.

Referenceable.

<Rationale>

Justification for a Decision. Must be a direct child of <Decision>. At most one per Decision.

<Rationale>
  Bidirectional references create synchronization burden.
</Rationale>

Attributes: None. Body text is the content.

Not referenceable.

<Alternative>

A considered option for a Decision. Must be a direct child of <Decision>. Each alternative records a choice that was not taken (or was deferred/superseded).

<Alternative id="bidirectional" status="rejected">
  Maintain forward and reverse refs in both documents.
</Alternative>

Attribute	Required	List	Description
id	yes	no	Unique identifier within the document
status	yes	no	rejected, deferred, or superseded

Referenceable.

Document Types

Documents declare their type and status in YAML front matter:

---
supersigil:
  id: auth/req/login
  type: requirements
  status: draft
---

Built-in Types

Type	Valid Statuses
requirements	draft, review, approved, implemented
design	draft, review, approved
tasks	draft, ready, in-progress, done
adr	draft, review, accepted, superseded

Custom document types can be defined in supersigil.toml. See Configuration for details.