Skip to content

Latest commit

 

History

History
1566 lines (1183 loc) · 89 KB

SDAIS.md

File metadata and controls

1566 lines (1183 loc) · 89 KB

SDAIS — Specification-Driven AI Synthesis

  • Date: 2026-10-08
  • Version: v0.13.0
  • Status: Draft

Idea

Specification-Driven AI Synthesis (SDAIS) is a software development paradigm in which humans author requirements exclusively, and AI agents synthesise, review, and refine all code. No human writes implementation code. The human role is that of architect and specifier; the AI role is that of implementer, reviewer, and annotator.

The name reflects the three load-bearing elements:

  • Specification-Driven — a structured, versioned requirements document is the single upstream artefact and the authoritative source of truth. All AI activity is derived from and traceable to it.
  • AI — one or more AI agents execute the full development lifecycle: generation, annotation, review, refinement, and test authoring.
  • Synthesis — the output is not a translation of human code, but a synthesis from requirements. The AI selects structure, idioms, and implementation strategy within the constraints given.

Reasoning

Traditional AI-assisted development treats AI as a tool inside a human workflow. The human retains code authorship; AI accelerates specific tasks. SDAIS inverts this: the human retains specification authorship; AI owns the implementation artifact entirely.

This inversion produces several consequences:

All implicit knowledge must become explicit. A human developer encodes architectural intent, naming rationale, and edge-case handling implicitly while writing code. In SDAIS, that knowledge must be stated in the specification or it does not exist. This raises the quality bar for requirements — and produces better-defined systems as a side effect.

Annotations become the cross-session memory of the AI. Because LLMs are stateless between invocations, the structured annotations embedded in generated code are the only mechanism by which a subsequent agent understands what a prior agent intended. Annotations are not documentation; they are the inter-agent protocol.

The programming language is a constraint, not a presumption. The specifier states the target language as a hard constraint, or leaves it unconstrained and lets the AI select. This makes the specification language-agnostic by default.

Refinement is a loop, not a one-shot operation. AI agents generate, review, and refine in cycles. Each cycle uses annotations from the prior cycle as its specification. The loop terminates when a review agent finds no violations and all acceptance criteria pass, or when a human approval gate is reached.

The annotation language is the AI-to-AI handoff protocol. It derives from Design by Contract (Meyer/Eiffel) — preconditions, postconditions, constraints — but is extended with traceability labels for multi-agent context. It operates at four scope levels: library, package, type, function.

Requirements and adopted libraries compose the implementation contract. Human-authored RSF decides whether and where a library applies. An adopted, pinned library file defines the referenced contract details. Approved ADF may explain and structure the solution, but may not weaken either authority. Implementation must satisfy the composed RSF plus library contract. RSF and an adopted library are complementary, not winner/loser alternatives: a contradiction between them blocks synthesis and must be reported by the SemanticAuditor. When ADF and generated code disagree without an RSF or library conflict, the ADF wins. No agent may silently reconcile a conflict.


Agent Environment and Model Contract

SDAIS is environment-agnostic: any AI agent system that can read and write files and maintain coherent context across a session is a valid execution environment. The following constraints apply regardless of platform.

Minimum Capability Requirements

An agent is suitable for any SDAIS role if it:

  • Can read and write Markdown files of arbitrary size within a single invocation.
  • Maintains sufficient context to process all active RSF items and annotated source files for the current version without truncation.
  • Produces structurally stable outputs — the same inputs on successive runs must not produce different artefact shapes unless the RSF changed.

Recommended Model Tiers

Pin the model version used for each agent in your project's AGENTS.md or equivalent configuration. Version drift between rounds — using a different model for round N+1 than for round N — can produce inconsistent finding interpretations.

Role Minimum recommended tier Reason
RequirementsEngineer High reasoning (e.g. Claude Opus) Ambiguity detection in free-form prose and requirement derivation benefit from deeper inference
TransformationEngineer High reasoning (e.g. Claude Opus) Ambiguity and Confidence elicitation in legacy-system prose require deeper inference
SemanticAuditor, SecurityAuditor High reasoning (e.g. Claude Opus) Ambiguity detection and security analysis benefit from deeper inference
Generator, Refiner, Analyzer, Transformation High coding ability (e.g. Claude Sonnet) Code synthesis and annotation precision are primary demands
Reviewer High reasoning or high coding (e.g. Claude Opus or Sonnet) Finding quality directly determines loop convergence speed
Architect, Grounder High reasoning (e.g. Claude Opus or Sonnet) Architecture decisions and infrastructure validation require sound judgment
TestGenerator High coding ability (e.g. Claude Sonnet) Test correctness and coverage require deep code understanding

Agent Output Storage

Specification and workflow outputs are files on disk within the sdais/ tree. Agent-managed product artefacts are files on disk within the active implementation root. No agent output is authoritative unless written to a file and committed to version control. The sdais/ tree, the implementation workspace, and git history together form the complete audit trail. External execution logs (API transcripts, tool call records) are supplementary and may be stored in sdais/logs/ if retention is required; they are never read by any agent.


Directory Structure

Every SDAIS project places all specification and workflow artefacts under an sdais/ directory at the project root. The AGENTS.md file lives at the project root as usual. Fresh projects place the complete agent-managed product workspace under implementation/.

<project-root>/
├── AGENTS.md
├── implementation/          ← agent-managed product workspace
│   ├── .sdais-root          ← zero-byte managed-root activation marker
│   └── <language-native project tree>
└── sdais/
    ├── SDAIS.md              ← paradigm specification (distribution file)
    ├── prompts/              ← installed by install; refreshed by update
    │   ├── requirements-engineer.md
    │   ├── transformation-engineer.md
    │   ├── semantic-auditor.md
    │   ├── grounder.md
    │   ├── architect.md
    │   ├── generator.md
    │   ├── reviewer.md
    │   ├── refiner.md
    │   ├── analyzer.md
    │   ├── transformation.md
    │   ├── security-auditor.md
    │   └── test-generator.md
    ├── library/              ← project-owned, versioned reference contracts
    │   └── <library-id>/
    │       └── v<N>/         ← immutable version; one or more UTF-8 text files
    ├── gspec/
    │   ├── v1/
    │   │   └── <anything>.md ← initial loose prose; any filename, any format
    │   └── v2/
    │       └── <same names>  ← RequirementsEngineer output with [[QN]] markers + ## Questions
    ├── tspec/
    │   ├── v1/
    │   │   └── <anything>.md ← initial prose about existing system + desired changes
    │   └── v2/
    │       └── <same names>  ← TransformationEngineer output with [[QN]] markers + ## Questions
    ├── rsf/
    │   ├── v1/
    │   │   ├── fr-0000-template.md       ← template; copy to start a new FR
    │   │   ├── nfr-0000-template.md      ← template; copy to start a new NFR
    │   │   ├── c-0000-template.md        ← template; copy to start a new Constraint
    │   │   ├── e-0000-template.md        ← template; copy to start a new Environment item
    │   │   ├── ac-0000-template.md       ← template; copy to start a new AC
    │   │   ├── fr-0001-<short-description>.md
    │   │   ├── fr-0002-<short-description>.md
    │   │   ├── nfr-0001-<short-description>.md
    │   │   ├── c-0001-<short-description>.md
    │   │   ├── e-0001-<short-description>.md
    │   │   └── ac-0001-<short-description>.md
    │   └── v2/
    │       └── ...            ← only items new or amended in v2
    ├── adf/                    ← Architecture Definition Files; produced by Architect
    │   └── v1/
    │       ├── adf-01-context-and-goals.md
    │       ├── adf-02-internal-architecture.md
    │       ├── adf-03-external-architecture.md
    │       ├── adf-04-requirement-trace.md
    │       ├── adf-05-glossary.md
    │       └── decisions/
    │           └── adr-0001-<short-title>.md
    ├── trs/
    │   ├── v1/
    │   │   ├── trs-fr-0000-template.md   ← template; copy to start a new TRS-FR
    │   │   ├── trs-nfr-0000-template.md  ← template; copy to start a new TRS-NFR
    │   │   ├── trs-c-0000-template.md    ← template; copy to start a new TRS-C
    │   │   ├── trs-fr-0001-<short-description>.md
    │   │   └── ...
    │   └── v2/
    │       └── ...
    ├── cdf/
    │   ├── v1/
    │   │   ├── lang-0001-<short-description>.md
    │   │   └── ...
    │   └── v2/
    │       └── ...

Version directory semantics:

  • Each gspec/v<N>/ directory is one iteration of the RequirementsEngineer clarification loop. The human writes initial prose into gspec/v1/; the agent creates gspec/v2/ with lightweight [[Q1]] inline markers and a ## Questions section per file; the human answers in gspec/v2/ by writing free prose below each ### QN: heading; the agent creates gspec/v3/ with answers incorporated, and so on. Files are not deleted between versions — each version is an immutable snapshot. The highest version that contains no open questions is the clean spec used for RSF generation.
  • Each tspec/v<N>/ directory is one iteration of the TransformationEngineer clarification loop. Semantics are identical to gspec/: immutable snapshots, inline [[QN]] markers and per-file ## Questions sections, highest clean version used for TRS and CDF generation.
  • Each rsf/v<N>/ directory contains all RSF items that are new or amended in version N. Items unchanged since their introduction remain in their original version directory and are still authoritative. Audit findings from the SemanticAuditor or Grounder are appended as ## Findings sections within the staged copies in rsf/v<N+1>/.
  • Each trs/v<N>/ directory contains TRS items introduced or amended in version N. Version semantics match those of rsf/.
  • Each cdf/v<N>/ directory contains CDF files for that transformation pass. CDFs are not versioned like RSF items; a new version directory is used when a new transformation pass is initiated.
  • Each adf/v<N>/ directory contains the Architecture Definition Files produced by the Architect for version N: context and goals, internal architecture, external architecture, requirement trace, glossary, and ADRs under decisions/. The five core filenames carry adf-01- through adf-05- prefixes so lexical order matches reading order. The directory is absent if the Architect step was skipped. Every file is UTF-8 Markdown.
  • Each library/<library-id>/v<N>/ directory is a published version of a project-owned reference library. Published version directories are immutable; amendments create v<N+1>/. The entire library/ directory may be absent or empty when no requirement uses it.
  • The distribution is sdais-vX.Y.Z.tgz. It contains SDAIS.md, README.md, CHANGELOG.md, LICENSE, install.sh, update.sh, sdais.sh, docs/, and scaffold/, and expands directly into the current directory. Create a project root, copy or download the archive into it, run tar xzf sdais-vX.Y.Z.tgz, then run ./install.sh <project-name> once to scaffold the project. To upgrade, unpack the new archive in the existing project root and run ./update.sh --from <old-version>. Run ./sdais.sh <tool> <model> <role> to launch any agent.
  • The prompts/ directory is installed by install and refreshed by update.

Implementation Root

The canonical implementation root is implementation/ at the project root. Managed-root mode is active only when the zero-byte marker implementation/.sdais-root exists. The root name is fixed in v0.13.0 and is not configurable.

In managed-root mode every product artefact written by Generator, Transformation, Refiner, or TestGenerator stays under implementation/. This includes source code, tests, module and package manifests, dependency lock files, fixtures, static assets, database migrations, build and deployment configuration, and product documentation. Language-native layout begins inside the root; for example a Go implementation uses implementation/go.mod, implementation/cmd/, and implementation/internal/. generated/ is not used because the committed, reviewed implementation is authoritative project content, not disposable build output. Agents must not create product artefacts beside AGENTS.md, the SDAIS distribution files, or sdais/.

The marker is an activation sentinel, not configuration. Fresh installation creates the directory and marker. Update never creates either for an existing unmarked project, never moves code, and never rewrites anything under an existing implementation/. An unmarked project retains legacy repository-wide and in-place behaviour exactly as before. To migrate deliberately, the human moves the complete implementation workspace into implementation/ and creates the zero-byte marker last. Directory existence without the marker does not activate managed-root mode.

For SDAIS-T in managed-root mode, existing legacy source may remain outside implementation/. Analyzer may read and add annotations to that source in place. Transformation writes the complete transformed target under implementation/ and never deletes the legacy source. If the source already lives under implementation/, Analyzer and Transformation operate there. After a transformed target exists, Generator gap-filling, Reviewer, Refiner, SecurityAuditor, and TestGenerator read or write only the managed target.

The implementation-root rule controls repository placement, not runtime file paths used by the product. An RSF, adopted library, or ADF decision that requires a repository product artefact outside the active managed root contradicts this workflow. SemanticAuditor reports CONTRADICTORY; synthesis and transformation stop rather than silently writing outside the root.

Versioned Reference Libraries

A library artifact is human-authored, local, versioned reference material that defines a reusable contract, language, protocol, schema, notation, design system, or interface. It is not requirement prose. Its existence never creates an FR, NFR, C, E, or AC, and agents do not load every library into global context.

The canonical layout is sdais/library/<library-id>/v<N>/<reference-file>, where <library-id> is stable lower-case kebab-case, v<N> is an explicit positive integer version, and reference files are UTF-8 text suitable for humans and agents. A published version is immutable. Remote contracts needed for reproducibility must first be captured as a local, reviewed snapshot; agents never fetch live definitions.

A requirement adopts a library only through an explicit **Libraries:** header. Each comma-separated entry is a project-root-relative path naming a concrete file, optionally followed by a Markdown heading anchor:

- **Source:** sdais/gspec/v3/ui.md
- **Libraries:** sdais/library/tds/v1/tds.md#8-workspace-and-coordinates

Source records provenance; Libraries records normative supporting contracts. They are never interchangeable. When Source exists, Libraries immediately follows it; otherwise it follows Last modified. The field is omitted when an item adopts no library. Unchanged items without it remain valid.

A valid pinned reference stays under sdais/library/<library-id>/v<N>/, contains an exact positive version and concrete filename, and resolves to an existing readable file and optional heading. URLs, absolute paths, floating latest aliases, unversioned or directory-only paths, path traversal, and references outside sdais/library/ are invalid. Local relative links inside a library may resolve only within the same version directory unless the link target is itself a valid pinned library reference. Agents read only the files reachable from active adopted references, retain those files as their own source of truth, and link to rather than copy large portions into RSF, ADF, annotations, code comments, or findings. Short paths such as library/tds/v1/tds.md are interpreted relative to sdais/; canonical fields use the full project-root-relative form.

File naming — why no date in the filename: Earlier versions of SDAIS embedded the authoring date in filenames (e.g. rsf-myproject-v1-2026-04-21.md) to timestamp versions without relying on version control. In the current structure each file carries its date in its header metadata, and git history is the authoritative timeline. Dates do not appear in filenames.


Lifecycle

┌──────────────────────────────────────────────────────┐
│  Human: loose prose in sdais/gspec/v1/                │
│  (any filenames, any format — no constraints)        │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
          ┌──────────────────────────┐
          │ AI: RequirementsEngineer │  inserts [[QN]] markers inline;
          │ (Clarification mode)     │  collects questions in ## Questions
          └──────────┬───────────────┘
                     │
          ┌──────────┴──────────┐
          │  open questions?    │
          └──┬───────────────┬──┘
             │ yes           │ no (spec clean)
             ▼               │
   Human answers below each  │
   ### QN: heading in the    │
   ## Questions section      │
             │               ▼
             └──────►  AI: RequirementsEngineer
                       (RSF Generation mode)
                       writes sdais/rsf/v1/
                       with **Source:** and applicable
                       **Libraries:** fields
                             │
                             ▼
                   Human reviews rsf/v1/;
                   amends, adds, or deletes
                             │
                             ▼
┌──────────────────────────────────────────────────────┐
│  Human: Requirements Specification (RSF)             │
│  FR · NFR · Constraints · Environment · Acceptance   │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
               ┌──────────────────┐
               │ AI: Semantic     │  checks RSF for ambiguity,
               │ Audit            │  library resolution, ambiguity,
               │                  │  contradictions, infeasibility
               └────────┬─────────┘
                        │
               ┌────────┴────────┐
               │  Findings?      │
               └──┬──────────┬───┘
                  │ yes      │ no (Cleared)
                  ▼          │
        Human amends RSF     │
        (version increment)  │
                  │          ▼
                  │   ┌─────────────────┐
                  │   │ AI: Grounder    │  verifies E- items against real infrastructure
                  │   └────────┬────────┘
                  │            │  ENV-UNRESOLVABLE findings?
                  │            ├── yes ──► Human amends E- items ──► re-run Grounder
                  │            │
                  │            ▼
                  │   ┌─────────────────┐
                  │   │ AI: Architect   │  optional; produces ADF set
                  │   │ (optional)      │
                  │   └────────┬────────┘
                  │            │  Human approves ADF?
                  │            ├── no ──► Architect revises
                  │            │
                  └───►        ▼
                        ┌──────────────────┐
                        │  AI: Generate    │  writes implementation/
                        │  (or TDD mode:   │  writes [ANN] blocks immediately
                        │   TestGen first) │
                        └────────┬─────────┘
                                 │
                        ┌────────▼─────────┐
                        │  AI: Review      │  validates annotations vs. code
                        │  (Round N)       │  writes FINDING/SEVERITY/HINT
                        │                  │  checks RSF acceptance criteria
                        └────────┬─────────┘
                                 │
                        ┌────────┴────────┐
                        │  violations?    │
                        └──┬──────────┬───┘
                           │ yes      │ no
                           ▼          ▼
                   ┌────────────┐  ┌──────────────────┐
                   │ AI: Refine │  │  Human: Approve  │
                   │  (Round N) │  │  or amend RSF    │
                   └─────┬──────┘  └──────────────────┘
                         │
                         │  all findings resolved?
                         ├── yes ──► Review (Round N+1)
                         │
                         └── waived (needs RSF change) ──► Human amends RSF

RSF amendments increment the version and restart the loop from the semantic audit. The prior annotated implementation workspace is not discarded — it becomes input context for the next generation pass.

Human prose or directly authored RSF may explicitly adopt a pinned file under sdais/library/. The RequirementsEngineer preserves the smallest applicable reference set on generated items; the SemanticAuditor resolves each reference and audits the composed contract. Architect, Generator, Reviewer, Refiner, TestGenerator, and—when security claims depend on interface definitions—SecurityAuditor then read those same pinned files. Library existence alone adds no context and produces no requirement.

For SDAIS-T (transformation of existing systems), the lifecycle starts at the SDAIS-T section (see below) and joins the standard SDAIS-G lifecycle at the Generator stage. In managed-root mode the annotated legacy source and RSF are Transformation inputs; its complete target under implementation/ is the input to Generator gap-filling and the standard review loop.


Usage Guide

Step −2 — Requirements Engineering (optional)

This step is optional. If you prefer to author RSF items directly, skip to Step −1. Use this step when you have rough ideas but struggle to write formal requirements from scratch.

Step −2.1 — Write initial specification prose

Create sdais/gspec/v1/ and write one or more files describing what the system should do. No filename convention or structure is required — bullet points, paragraphs, conversation fragments, or any other form are all accepted.

Step −2.2 — Run the RequirementsEngineer (Clarification mode)

Provide all files in sdais/gspec/v1/ to the RequirementsEngineer agent. Use the prompt from sdais/prompts/requirements-engineer.md.

The agent reads every spec file and identifies passages that are ambiguous, use undefined terms, lack measurable bounds, or are missing acceptance criteria. For each such passage it inserts a lightweight [[Q1]] marker inline immediately after the affected text and appends a ## Questions section at the bottom of the file (after a — separator) with the full question text as a ### Q1: heading. The processed files are written to sdais/gspec/v2/ under the same filenames.

The agent also recognizes explicit pinned references such as sdais/library/tds/v1/tds.md. It reads a referenced file to understand its defined terms, preserves the reference and its scope through later prose versions, and asks a clarification question when a library is named informally, lacks an exact version or file, or has unclear adoption scope. A library file is never treated as another gspec input and never generates requirements by itself.

Step −2.3 — Answer the questions

Open each file in sdais/gspec/v2/ that has a ## Questions section. For each ### QN: heading that has no answer below it, write your answer as free prose immediately below the heading.

Do not remove, reword, or add ### QN: headings — questions are written exclusively by the RequirementsEngineer, not by humans.

Re-run the RequirementsEngineer. Repeat until the agent reports zero open questions.

Step −2.4 — RSF Generation

When no open questions remain the RequirementsEngineer switches to RSF Generation mode automatically. It reads the clean spec files and writes one RSF item file per derived requirement into sdais/rsf/v1/. Each generated item carries a **Source:** field listing the spec file(s) it was derived from and, when applicable, a **Libraries:** field containing only the pinned references that govern that item.

Step −2.5 — Human review of generated RSF

Review every item in sdais/rsf/v1/:

  • Amend wording that is technically correct but does not match your intent.
  • Delete items that are artefacts or duplicates.
  • Add items the RequirementsEngineer could not derive (it can only work from what is in the spec prose).

The **Source:** field is the audit trail linking each RSF item back to human intent. Do not delete it.

When satisfied with sdais/rsf/v1/, proceed to Step −1 or directly to Step 0.


Step −1 — Initialise the Project

Before authoring any RSF items, run install from the project root to scaffold the sdais/ directory tree:

./install <project-name>

This copies SDAIS.md to sdais/SDAIS.md, installs all prompt files into sdais/prompts/, installs all *-0000-template.md files, creates an empty project-owned sdais/library/, creates implementation/.sdais-root to activate managed-root mode, and writes AGENTS.md at the project root with the project name substituted. No project-specific library content ships in the scaffold.

To launch an agent from the project root, use ./sdais.sh:

./sdais.sh <tool> <model> <role>

For example: ./sdais.sh claude claude-opus-4-5 SemanticAuditor. The launcher accepts the role as CamelCase (SemanticAuditor) or kebab-case (semantic-auditor). Supported tools: claude, ollama. Run from the project root.

Step −1b — Update Scaffolding to a New SDAIS Version

When upgrading to a new SDAIS version, replace SDAIS.md, install, and update (and the tgz or scaffold/ directory) with the new release, then run from the project root:

./update --from <old-version>

update replaces all scaffold files while leaving all project content untouched.

What is scaffolding vs. project content:

Refreshed by update Left untouched
AGENTS.md (Custom Agents Extension preserved) sdais/gspec/v*/*.md
All files in sdais/prompts/ sdais/tspec/v*/*.md
All *-0000-template.md files sdais/rsf/v*/fr-NNNN-*.md (NNNN ≥ 0001)
sdais/SDAIS.md sdais/rsf/v*/nfr-NNNN-*.md (NNNN ≥ 0001)
sdais/rsf/v*/c-NNNN-*.md (NNNN ≥ 0001)
sdais/rsf/v*/e-NNNN-*.md (NNNN ≥ 0001)
sdais/rsf/v*/ac-NNNN-*.md (NNNN ≥ 0001)
sdais/trs/v*/*.md
sdais/cdf/v*/*.md
sdais/adf/v*/*.md
sdais/library/** (all project-owned versions and files)
implementation/** (including .sdais-root)
All legacy source code outside implementation/

Update does not add implementation/.sdais-root to an unmarked legacy project. Such a project remains in legacy mode until the human completes the documented migration and creates the marker.


Step 0 — Semantic Audit Loop

Before any code is generated the RSF must pass a semantic audit. The SemanticAuditor does not modify the content of any RSF file in rsf/v<N>/; it stages amended copies in rsf/v<N+1>/ with findings appended.

Step 0.1 — Run the SemanticAuditor

Provide all RSF item files for the current version to the SemanticAuditor. Use the prompt from sdais/prompts/semantic-auditor.md. The agent copies each RSF item that has at least one finding to sdais/rsf/v<N+1>/ and appends a ## Findings section (after a — separator) with one ### F<n>: entry per finding. RSF files with no findings are not copied. The agent outputs a summary of all findings and staged files.

Finding categories: AMBIGUOUS | INCOMPLETE | CONTRADICTORY | INFEASIBLE | UNTESTABLE | UNQUANTIFIED | LIBRARY-UNRESOLVABLE.

Step 0.2 — Review each finding

Each ### F<n>: entry in the staged RSF files ends in a list of solution variants (see Findings Appendix Format). For each finding the human ticks exactly one variant — - [x] — replaces every {{placeholder}} in the ticked line, and applies it in rsf/v<N+1>/ according to its action. If no variant fits, the human ticks Own and writes the resolution there.

Variant action When it is offered What to do in rsf/v<N+1>/
Fix Item kept; wording corrected or quantified Replace the ## Requirement text above the — separator with the variant text
Drop Item irrecoverably ambiguous or no longer needed Delete the file from rsf/v<N+1>/; set Status to Dropped in the original
Supersede Replace with a cleaner formulation under a new ID Create a new item file with the variant text; the ticked variant records the supersession
Split One item covered two distinct concerns Create one new item file per variant text; the ticked variant records the split
Waive Finding acknowledged; item intentionally unchanged Leave the requirement text unchanged; the filled {{rationale}} records why

Rules for RSF item IDs:

  • IDs are never reused. A dropped or superseded item file remains as a tombstone with Status: Dropped or Status: Superseded.
  • New items introduced during an amendment use the next available sequential number in their prefix group.

Step 0.3 — Re-audit or proceed

  • A finding is resolved when exactly one variant is ticked and that line contains no {{placeholder}}.
  • If any finding remains unresolved: return to Step 0.1 with the new RSF version.
  • If all findings are resolved: proceed to Step 0.4 if the RSF contains any E- items, otherwise proceed to Step 1.

An active item with an unresolved **Libraries:** entry cannot be Cleared. LIBRARY-UNRESOLVABLE variants repair or remove only the reference and never invent adoption intent. Contradictions between an RSF item and its library, between adopted libraries, or between an AC and its library use CONTRADICTORY, not LIBRARY-UNRESOLVABLE.

Step 0.4 — Infrastructure Grounding (mandatory when E- items are present)

Run the Grounder agent when any active E- item exists in the cleared RSF. Use the prompt from sdais/prompts/grounder.md.

The Grounder reads every E- item and attempts to confirm that each named infrastructure element (database, service endpoint, message queue, file path, API, etc.) exists and matches the item description. For each confirmed element the Grounder sets **Verified:** true. For each element that cannot be confirmed the Grounder appends an ENV-UNRESOLVABLE finding to the E- item file staged in sdais/rsf/v<N+1>/.

Library files are not infrastructure and are never converted to E-items. The Grounder may read an adopted contract only when needed to understand an E-item; the SemanticAuditor remains responsible for reference validation.

Resolution paths for ENV-UNRESOLVABLE findings:

Action When to use Result
Fix Update the E- item to match what actually exists Grounder re-runs; item receives **Verified:** true
Drop The named element does not and will not exist Drop the E- item and any dependent FR items
Waive Infrastructure is to be created by this project Note in **Resolution:** that the element will be built as part of this project

After all ENV-UNRESOLVABLE findings are resolved or waived: proceed to Step 1.

The full prompt is in sdais/prompts/grounder.md.


Step 1 — Requirements Specification (RSF)

Each RSF item is one Markdown file in sdais/rsf/v<N>/. The prefix encodes the item type:

Prefix Type
fr-NNNN- Functional Requirement
nfr-NNNN- Non-Functional Requirement
c-NNNN- Constraint
e-NNNN- Environment
ac-NNNN- Acceptance Criterion

RSF item file format:

# FR-0001: Short Title of the Requirement

- **Type:** Functional Requirement
- **Status:** Active
- **Introduced:** v1 (2026-04-21)
- **Last modified:** v1 (2026-04-21)
- **Source:** sdais/gspec/v3/auth-requirements.md
- **Libraries:** sdais/library/example-api/v2/openapi.yaml#paths

## Requirement

The service must authenticate requests using an API key supplied in the
`X-API-Key` HTTP header. Requests without a valid key must be rejected
with HTTP 401.

Related: [FR-0003], [NFR-0002], [AC-0001]

The **Source:** field records which spec file(s) are the primary reason for this item. It is written by the RequirementsEngineer when generating RSF items from prose; it may be omitted when a human authors an RSF item directly without going through Step −2.

The optional **Libraries:** field records exact pinned supporting contracts. Multiple references are comma-separated. It immediately follows Source, or Last modified when Source is absent. Paths and anchors must resolve before Cleared status; items without the field remain valid.

Environment (E-) items carry an additional field set by the Grounder:

# E-0001: Short Title of the Environment Item

- **Type:** Environment
- **Status:** Active
- **Introduced:** v1 (2026-04-21)
- **Last modified:** v1 (2026-04-21)
- **Libraries:** sdais/library/deployment-schema/v1/environment.md
- **Verified:** Pending

## Requirement

<description of the runtime or deployment environment element>

Related: [FR-NNNN]

**Verified:** values: Pending (initial, set by human at authoring), true (confirmed by Grounder), false is not used — an unconfirmed element produces an ENV-UNRESOLVABLE finding appended to the item file and the field remains Pending.

Rules:

  • The ## Requirement section text is the authoritative, current formulation. When an item is fixed in place the section text is rewritten; the old wording is not preserved above the — separator (the ## Findings section and git history preserve the rationale).
  • Items that are Dropped or Superseded set Status: accordingly and retain their ## Requirement text as a tombstone.
  • Cross-references use [FR-NNNN], [NFR-NNNN], [AC-NNNN], etc. without version — they resolve to the most recent active version of the referenced item.

Architecture Definition

Step 1b is optional and skipped unless either of the following conditions holds:

  • The cleared RSF contains at least one C- item that explicitly requires design approval (i.e., its text calls for architectural sign-off before code is generated).
  • The human explicitly invokes the Architect.

When Step 1b runs, provide all cleared RSF items and the library files reachable from their **Libraries:** fields to the Architect agent. Use the prompt from sdais/prompts/architect.md.

The Architect reads all active RSF items plus their resolved library closures and produces an Architecture Definition File set (ADF) under sdais/adf/v<N>/. The set separates concerns so that architecture can be reviewed, linked, and evolved without rewriting one monolithic document. The Architect does not read or write source code and does not write [ANN] blocks.

ADF document set:

File Required content
adf-01-context-and-goals.md Context, goals, stakeholders, scope, quality goals, and constraints.
adf-02-internal-architecture.md Components, responsibilities, implementation-root-relative locations, owned data, boundary contracts, data flows, pinned libraries realized by components and internal interfaces, and at least one Mermaid component or dependency diagram.
adf-03-external-architecture.md Actors, external systems, integrations, trust boundaries, failure handling, integration flows, external API/schema/protocol libraries realized, and at least one Mermaid context or integration diagram.
adf-04-requirement-trace.md One row per active RSF item, mapping its ID and exact title to a Library References column containing exact pinned paths or —, architecture components, external interfaces, decisions, and verification.
adf-05-glossary.md Project, domain, integration, component, data, and acronym terms.
decisions/adr-NNNN-<short-title>.md One Architecture Decision Record per significant decision, numbered contiguously from ADR-0001.

All ADF documents are UTF-8 Markdown. Each of the five core documents starts with:

# <Document Title> — <project> v<N>

- **RSF Version:** v<N>
- **Status:** Draft | Approved | Superseded
- **Architect:** <agent run date>

Every ADR has the following sections in order:

# ADR-NNNN: <Decision Title>

- **Status:** Proposed | Accepted | Rejected | Superseded
- **Date:** <agent run date>

## Context

## Decision

## Justification

## Consequences

## Alternatives

## Relevant Requirements

- **[<id>]:** <text>

## Verification Tests

- **[<id>]:** <text>

Relevant Requirements and Verification Tests are non-empty item lists. Every item has the exact form - **[<id>]:** <text>, where <id> is a real specification ID and <text> is its exact title. The Architect never invents specification IDs. Every active RSF item appears exactly once in the requirement trace, and every active FR maps to at least one internal component and verification. Component names remain identical throughout the set. Mermaid diagrams are added wherever needed to make non-trivial internal flows or integrations unambiguous.

In managed-root mode every component, interface, test location, manifest, and deployment path in the ADF is under implementation/. The ADF does not direct Generator to create product files at the project root. A conflicting path decision is returned to semantic audit.

ADF wording links to library definitions rather than duplicating them. UI and design-language libraries are reflected in internal interfaces and relevant ADRs; external API, schema, and protocol libraries are reflected in external architecture and integration contracts. Every component and interface names the pinned libraries it realizes. An ADF decision may not silently change a library-defined rule; any conflict returns to semantic audit.

Human review gate: the human reads the complete ADF set and either:

  • Approves — sets all five core document statuses to Approved and every ADR status to Accepted; proceed to Step 2.
  • Rejects — provides written feedback; the Architect revises the set and the human reviews again.

Generator reads the ADF: if sdais/adf/v<N>/ exists, all five core documents have **Status:** Approved, and every ADR has **Status:** Accepted, the Generator reads the complete set as structural context before synthesising. An incomplete or partly approved set is not used. Human-authored RSF determines adoption and scope; RSF plus adopted libraries are the implementation contract, and ADF is subordinate structural guidance.

The full prompt is in sdais/prompts/architect.md.


Step 2 — Instruct the Generator Agent

Provide all active RSF item files and each item's resolved library closure to the Generator. Use the prompt from sdais/prompts/generator.md.

The full prompt is in sdais/prompts/generator.md. Summary of agent behaviour: reads all active RSF items and only their adopted library closures; reads the complete sdais/adf/v<N>/ set as structural context if all core documents are Approved and all ADRs are Accepted; synthesises a complete implementation of the composed contract under the active implementation root; writes one [ANN] block per callable unit and type with (ANN-ID) as the first label; sets (AGENT) to Generator, (VERIFIED) to false, and (ROUND) to 0 on every block; outputs a summary of files created and RSF items addressed. It stops and reports affected IDs rather than guessing if a reference cannot resolve, a contract conflict remains, or managed-root placement cannot be honoured.

Step 2 — TDD Mode (optional)

TDD mode inverts the normal generation order. The TestGenerator runs before the Generator and produces test files with failing assertions. The Generator then synthesises implementation targeting those tests.

Activating TDD mode: the human adds a C- item to the RSF: C-NNNN: Generation mode: TDD.

TDD mode steps:

  1. Run the TestGenerator in TDD mode: reads all FR, AC, and NFR items plus their adopted libraries; writes test files under the active implementation root with test functions that assert expected behaviour—including relevant boundary, grammar, compatibility, and conformance rules—but have no passing implementation. Each test function receives an [ANN] block with (AGENT) TestGenerator, (VERIFIED) false, (ROUND) 0, and (TEST-MODE) TDD.
  2. Run the Generator: reads all active RSF items, the ADF set (if present and fully approved), and the test files from step 1. Synthesises implementation targeting a 100% pass rate on those tests. Writes [ANN] blocks as normal. Does not set (TEST-MODE) — that label is exclusive to TestGenerator.
  3. Continue with the standard Review → Refine loop. The Reviewer additionally verifies that all (TEST-MODE) TDD blocks pass against the generated implementation.

Step 3 — Run the Review Agent

Provide the generated, annotated code, all active RSF item files, and their resolved library closures to the Reviewer. Use the prompt from sdais/prompts/reviewer.md. Pass the current round number (starts at 1 after the first Generate pass).

The full prompt is in sdais/prompts/reviewer.md. Summary of agent behaviour: in managed mode reads annotated files only under implementation/; checks every [ANN] block against the composed requirement and implementation; records library conformance and managed-root placement failures on the relevant [ANN] block; keeps (ORIGIN) limited to RSF/TRS IDs rather than filesystem paths; sets (VERIFIED) and updates (AGENT) and (ROUND) on every block; runs a dependency cascade check; outputs a structured summary.

Review-loop tracking:

Each review pass increments the round number. The (ROUND) label in every [ANN] block records which pass last touched it. New findings appended in round N get the next available local index in the block — they are never renumbered to avoid collision with prior (FINDING:n:STATUS) entries.


Step 4 — Run the Refiner Agent (if violations exist)

Provide the reviewed, annotated code, its active RSF origins, and the same pinned library files to the Refiner. Use the prompt from sdais/prompts/refiner.md. Pass the same round number used in the Review pass.

The full prompt is in sdais/prompts/refiner.md. Summary of agent behaviour: reads the same pinned contracts used by the Reviewer; corrects implementation as directed by (HINT:n); appends (FINDING:n:STATUS); updates only permitted annotation fields when a fix makes them factually incorrect; never edits RSF or library content; sets (VERIFIED) and (AGENT) to reflect resolution outcome; outputs a structured summary.

After each Refiner pass:

  • If any blocks remain (VERIFIED) false due to Resolved findings (not Waived): run the Reviewer again at round N+1.
  • If all remaining (VERIFIED) false blocks have only Waived findings: the human amends the RSF (new version), then returns to Step 0.

Step 5 — Human Approval Gate

When the Reviewer reports zero violations and all acceptance criteria pass, the human reviews the output. Three outcomes:

  • Approve — synthesis complete; RSF files and the annotated implementation workspace are archived together.
  • Amend RSF — increment RSF version, restart loop with existing codebase as context.
  • Reject — provide written rationale; restart loop from generation.

Rollback procedure: If the human determines that the current annotated codebase is irrecoverably diverged from RSF intent, they may roll back to a prior committed state using git. Rolling back does not require discarding the RSF — it requires re-running from the Generator step with the rolled-back codebase as input context. The rolled-back commit and the RSF version that triggered the restart must both be referenced in the next commit message.

Escalation: When a waived finding requires an RSF amendment that itself produces new semantic-audit findings, and this cycle repeats more than twice without convergence, the human must halt the loop, record a CONTRADICTORY or INFEASIBLE finding in the affected RSF item capturing the impasse, and decide whether to simplify scope or seek architectural intervention before resuming.

Approval record: When approving, the human records the approval in the commit message with the format Approved: RSF v<N>, Round <R>. This is the minimum traceability record. Teams may supplement it with an approval field in the ADF.


SDAIS-T: Transformation Extension

Concept and Positioning

The standard SDAIS lifecycle assumes a greenfield project: the specification precedes the code, and the Generator synthesises from scratch. Transformation inverts this. The existing codebase is the primary artefact; specification must be derived from it. Greenfield agents cannot operate on code that has no RSF, no [ANN] blocks, and no verified requirements.

The core inversion is: code + fuzzy prior knowledge → specification → transformed code. Prior knowledge — architecture diagrams, design notes, institutional memory — is captured as TRS items (Transformation Specification). TRS items are hypotheses, not assertions. The code is always authoritative when it contradicts a hypothesis. In managed-root mode legacy source remains an input artefact and the transformed target is a separate complete workspace under implementation/.

SDAIS-T produces inputs that feed into the standard SDAIS lifecycle from the Generator stage onwards. Analyzer annotates the existing codebase and derives RSF items. Transformation applies CDFs and, in managed-root mode, writes the complete implementation/ target that Generator gap-filling, Reviewer, and Refiner consume. Legacy mode retains the earlier in-place handoff.

SpecificationEngineer Archetype

Both RequirementsEngineer and TransformationEngineer are instances of the SpecificationEngineer archetype: each accepts free-form prose, refines it through an iterative clarification loop, and produces formal SDAIS artefacts. RequirementsEngineer produces RSF items from sdais/gspec/; TransformationEngineer produces TRS items and CDF files from sdais/tspec/. The clarification protocol is identical: lightweight [[QN]] markers appear inline at each ambiguous point in the prose; the full question text and human answers accumulate in a ## Questions section at the bottom of each file. The output schema differs between the two agents.

Both engineers recognize explicit pinned library references in the highest input version, read them for defined terms, preserve them through later prose versions, and attach only the smallest applicable set to each output item. They do not treat library files as gspec/tspec inputs or derive standalone items from library content. Informal, unversioned, file-less, or ambiguously scoped adoption triggers a clarification question.

Extended Lifecycle Diagram

TRS (fuzzy prior knowledge + transformation intent)
    │  adopts exact files from sdais/library/<id>/v<N>/ when applicable
    │
    ▼
Analyzer Agent ──► Annotated existing code + RSF v1 (with library refs/findings)
    │
    ▼
Semantic Audit Loop (resolves libraries; audits composed contract)
    │
    ▼
Cleaned RSF + Annotated existing code
    │
    ▼
Human activates CDF(s)
    │
    ▼
Transformation Agent ──► implementation/ target with stable ANN-IDs
    │
    ▼
═══ Transition to Standard SDAIS Lifecycle ═══
    │
    ▼
Generator (gaps only) → Reviewer → Refiner → ...

The Analyzer reads the existing codebase and any available TRS items, adds [ANN] blocks to every callable unit and type in place, derives RSF items from observed behaviour, and appends findings to RSF item files for anything unclear. The resulting artefacts pass through the standard Semantic Audit Loop. The human then activates CDF files defining the desired transformations. In managed-root mode Transformation reads the annotated source without moving or deleting it, writes the complete target under implementation/, preserves all (ANN-ID) values, and hands that target to Generator for uncovered RSF items. Reviewer, Refiner, SecurityAuditor, and TestGenerator then scope their work to implementation/. Legacy mode retains the prior in-place flow.

SDAIS-T Step −2 — Transformation Engineering (optional)

This step is optional. If you prefer to author TRS items and CDF files directly, skip to Step −1. Use this step when you have rough ideas about the existing system and desired changes but struggle to express them in formal TRS and CDF format.

Step −2.1 — Write initial transformation prose

Create sdais/tspec/v1/ and write one or more files describing the existing system and the transformations you want to apply. No filename convention or structure is required.

Step −2.2 — Run the TransformationEngineer (Clarification mode)

Provide all files in sdais/tspec/v1/ to the TransformationEngineer agent. Use the prompt from sdais/prompts/transformation-engineer.md.

The agent identifies passages that are ambiguous, use undefined terms, make tacit assumptions about legacy system behaviour, or state transformation goals without measurable targets. For each such passage it inserts a lightweight [[Q1]] marker inline and appends a ## Questions section at the bottom of the file with the full question text as a ### Q1: heading. The processed files are written to sdais/tspec/v2/.

Step −2.3 — Answer the questions

Open each file in sdais/tspec/v2/ that has a ## Questions section. For each ### QN: heading that has no answer below it, write your answer as free prose immediately below the heading.

Do not remove, reword, or add ### QN: headings — questions are written exclusively by the TransformationEngineer, not by humans.

Re-run the TransformationEngineer. Repeat until the agent reports zero open questions.

Step −2.4 — Output Generation

When no open questions remain the TransformationEngineer switches to Output Generation mode automatically. It writes TRS item files to sdais/trs/v1/ and CDF files to sdais/cdf/v1/. Each TRS item carries a **Confidence:** field and a **Source:** field. TRS and CDF headers carry **Libraries:** immediately after Source when they adopt a library. Each CDF carries **Status:** Draft — the human must change this to Active before running the Transformation agent.

Step −2.5 — Human review of generated TRS and CDF files

Review every item in sdais/trs/v1/ and every file in sdais/cdf/v1/:

  • Amend TRS item wording that does not match your understanding of the system.
  • Delete items that are artefacts or duplicates.
  • Add TRS items the agent could not derive.
  • For each CDF you intend to apply, change **Status:** from Draft to Active.

The **Source:** fields trace each TRS item and CDF back to the original prose. Do not delete them.

When satisfied, proceed to the Analyzer step.

TRS — Transformation Specification

Each TRS item is one Markdown file in sdais/trs/v<N>/. TRS items represent hypotheses about what the existing system does. They are input context for the Analyzer; they do not drive code generation directly.

File naming: same scheme as RSF — trs-fr-NNNN-<short-description>.md, trs-nfr-NNNN-<short-description>.md, trs-c-NNNN-<short-description>.md.

TRS item file format:

# TRS-FR-0001: LDAP Authentication Subsystem

- **Type:** Functional Requirement
- **Status:** Hypothesis
- **Introduced:** v1 (2026-05-02)
- **Confidence:** Medium
- **Source:** sdais/tspec/v3/auth-system.md
- **Libraries:** sdais/library/ldap-api/v1/protocol.md

## Hypothesis

The system authenticates users against a corporate LDAP directory. Credentials
are validated by binding to the LDAP server with the supplied username and
password. A successful bind grants access; a failed bind returns an
authentication error.

## Evidence

- Class `LdapAuthProvider` in `auth/ldap.java` performs a bind operation.
- Configuration key `ldap.server.url` present in `config/app.properties`.
- No alternative authentication path found in the codebase.

## Open Questions

- Is there a fallback to local credential store when LDAP is unreachable?
- Are group memberships retrieved and mapped to application roles?

The **Source:** field records which tspec file(s) are the primary reason for this item. It is written by the TransformationEngineer when generating TRS items from prose; it may be omitted when a human authors a TRS item directly without going through Step −2.

The optional **Libraries:** field has the same pinned-reference syntax as RSF. It immediately follows Source, or Confidence when Source is absent. It records normative supporting contracts and is not provenance. In CDF it immediately follows Source, or Affects when Source is absent.

Status values:

Value Meaning
Hypothesis Initial state; not yet validated against code
Confirmed Analyzer or human verified the hypothesis against the code
Refuted Code contradicts the hypothesis; Analyzer appended a TRS-CONTRADICTS-CODE finding to the RSF item
Refined Hypothesis was partially correct; amended after Analyzer findings

Confidence semantics:

Value Meaning Analyzer behaviour
High Strong evidence in code or cited documentation Analyzer performs sample-check validation
Medium Partial evidence; behaviour likely but not certain Analyzer validates each claim carefully
Low Weak hypothesis; tacit assumption with little direct evidence Analyzer performs deep code analysis before accepting

CDF — Change Definition File

Each CDF in sdais/cdf/v<N>/ describes exactly one dimension of change. CDFs are orthogonal and combinable — multiple active CDFs can transform the same codebase in one transformation pass.

File naming: <category>-NNNN-<short-description>.md. Categories:

Prefix Category
lang- Language migration
ui- UI framework change
i18n- Localisation / language selection
pers- Persistence layer change
mod- Modularisation (monolith ↔ modules ↔ services)
plat- Platform change (bare metal, container, cloud)
api- API style change (REST, gRPC, sync, async)
obs- Observability introduction

**Status:** values: Draft (generated by TransformationEngineer; not yet applied) or Active (human-promoted; ready for the Transformation agent).

CDF file format:

# lang-0001: Java 8 to Go 1.22 Migration

- **Type:** Language Migration
- **Status:** Active
- **Introduced:** v1 (2026-05-02)
- **Affects:** all
- **Source:** sdais/tspec/v3/migration-goals.md
- **Libraries:** sdais/library/target-api/v2/openapi.yaml

## Source

Language: Java 8
Build system: Maven 3.x
Runtime: JVM 8 on Linux/amd64

## Target

Language: Go 1.22
Build system: Go modules
Runtime: Native binary on Linux/amd64

## Transformation Rules

1. Each Java class with only static methods becomes a Go package; the class
   name becomes the package name in lowercase.
2. Each Java class with instance state becomes a Go struct; instance methods
   become methods on the struct.
3. Java interfaces become Go interfaces. Method signatures are translated
   directly; checked exceptions become additional error return values.
4. Java generics are translated to Go generics where a direct mapping exists;
   where no direct mapping exists, use the most specific concrete type and append
   a CODE-INTENT-UNCLEAR finding to the affected RSF item file.
5. Maven dependency `org.apache.commons.lang3` is replaced by Go standard
   library equivalents. No third-party replacements.
6. Maven dependency `org.slf4j` is replaced by `log/slog` from the Go standard
   library.
7. LDAP operations using `com.unboundid.ldap.sdk` are replaced by
   `github.com/go-ldap/ldap/v3`.

## Constraints to Preserve

- All (CONSTRAINT:SEC) labels from the existing [ANN] blocks must be present
  in the transformed code.
- All (CONSTRAINT:AVAIL) labels must be present in the transformed code.
- Public API surface (function names, parameter semantics) must remain
  identical where the API is referenced by an active RSF item.

## Acceptance

- All RSF items with Status Active are addressed by at least one [ANN] block
  in the transformed codebase.
- go build completes without errors.
- go vet reports no issues.
- All (ANN-ID) values from the original codebase are present in the transformed
  codebase, subject to split and merge rules.

The **Affects:** field lists either specific (ANN-ID) references (comma-separated) or all. When set to all, the transformation rules apply to every unit in the codebase.

Analyzer Agent

The Analyzer operates in three-output mode:

  1. Annotates the existing codebase additively. Every callable unit and every type receives an [ANN] block with a freshly generated (ANN-ID), reconstructed (TASK), inferred (PRE) and (POST), and a (CONFIDENCE) label. Existing logic, signatures, and comments are never modified. In managed-root mode this is the sole role permitted to write annotations into legacy source outside implementation/. Where a TRS item ID maps confidently to a unit, (ORIGIN) is set to that TRS item ID.

  2. Derives formal RSF item files in sdais/rsf/v1/. Each distinct observable behaviour, quality attribute, or constraint inferred from the code becomes one RSF item.

    When the behavior depends on a validated library adopted by a relevant TRS or active CDF, the derived RSF item carries that smallest relevant pinned set in **Libraries:**. A library never creates an RSF item by itself.

  3. Appends findings to RSF item files staged in sdais/rsf/v<N+1>/ for any unclear mappings, using the transformation finding categories TRS-CONTRADICTS-CODE and CODE-INTENT-UNCLEAR.

The full prompt is in sdais/prompts/analyzer.md.

Transformation Agent

The Transformation agent reads the annotated existing codebase, all active CDF files, all active RSF files, and only their resolved library closures. It applies each CDF's transformation rules to the units listed in Affects:, implements the composed RSF plus library contract, and preserves all (ANN-ID) values according to the split and merge rules below. In managed-root mode it writes a complete transformed target under implementation/; it never deletes the source or emits target files elsewhere. It stops and reports affected RSF/CDF IDs without guessing when a reference cannot resolve, a conflict remains, or root placement cannot be honoured.

(ANN-ID) preservation rules:

  • One-to-one: the transformed unit carries the original (ANN-ID) unchanged.
  • Split: when one original unit splits into multiple new units, the original (ANN-ID) stays with the unit retaining primary responsibility. Each additional new unit receives a freshly generated (ANN-ID) as ANN-<8-hex>.
  • Merge: when multiple original units merge into one, the merged unit lists all original (ANN-ID) values in its (ANN-ID) field, separated by commas.

After transformation, any RSF items not covered by the transformed units are handed to the Generator agent.

The full prompt is in sdais/prompts/transformation.md.


AGENTS.md — Custom Agents Extension

Marker Syntax

Custom agent entries in AGENTS.md are delimited by HTML comment markers:

<!-- BEGIN: Custom Agents Extension -->
...user-defined content...
<!-- END: Custom Agents Extension -->

These markers are invisible in rendered Markdown and unambiguous for tooling.

Update Contract

Any tool, prompt, or human that regenerates AGENTS.md must preserve the entire content between the markers verbatim, including ordering and formatting. Only content outside the markers may be replaced.

Custom Agent Entry Schema

#### <AgentName>

- **Role:** <one-line description>
- **Triggers:** <when this agent is invoked in the lifecycle>
- **Reads:** <which artefacts the agent consumes>
- **Writes:** <which artefacts the agent produces>
- **Annotation Permissions:** <which [ANN] fields the agent may modify>
- **Prompt:** `sdais/prompts/<agent-name>.md`

Worked Examples

DomainAuditor

  • Role: Validates domain-specific business rules beyond functional correctness.
  • Triggers: Runs after Reviewer in each review round.
  • Reads: Annotated source files; active RSF items; domain rule catalogue.
  • Writes: (FINDING:n), (SEVERITY:n), (HINT:n) labels on affected [ANN] blocks. Prefixes all finding descriptions with DOMAIN-.
  • Annotation Permissions: Same as Reviewer — appends finding labels; updates (AGENT), (VERIFIED), (ROUND).
  • Prompt: sdais/prompts/domain-auditor.md

ComplianceAuditor-GDPR

  • Role: GDPR-specific data-flow audit; verifies that all personal data handling complies with GDPR requirements.
  • Triggers: Runs mandatorily before any approval gate when at least one active [ANN] block carries (CONSTRAINT:SEC) PII.
  • Reads: Annotated source files; active RSF items; GDPR compliance checklist.
  • Writes: (FINDING:n), (SEVERITY:n), (HINT:n) labels on affected [ANN] blocks. Prefixes all finding descriptions with GDPR-.
  • Annotation Permissions: Same as SecurityAuditor — appends finding labels for (CONSTRAINT:SEC) violations; updates (AGENT), (VERIFIED), (ROUND).
  • Prompt: sdais/prompts/compliance-auditor-gdpr.md

Rules

Custom agents may use any subset of the standard annotation mutation permissions defined in the Annotation Mutation Rules table. A custom agent may define its own finding prefix (e.g. DOMAIN-, GDPR-) to distinguish its findings from standard agent findings in (FINDING:n) descriptions.

Custom agent prompts live in sdais/prompts/ alongside the standard prompts, and are versioned through git.


Annotation Syntax

Block Structure

An annotation block is a contiguous comment block opened by the sentinel [ANN]. It is separate from any human-facing doc comment. Each label occupies one line. Labels are written and read by agents only — not by humans during normal development.

Go — Generator output (Round 0):

// [ANN]
// (ANN-ID)      ANN-7f3a9c2e
// (ORIGIN)      FR-0003, NFR-0001
// (TASK)        Parse IMAP server address and validate format.
// (CONTEXT)     Called once at startup before any connection is attempted.
// (CONSTRAINT)  Address must include host and port; scheme is not validated.
// (PRE)         raw is a non-empty string.
// (INPUT)       raw string — address as provided by the caller
// (OUTPUT)      host string — validated hostname or IP
// (OUTPUT)      port int    — validated port number
// (POST)        host is non-empty; 1 <= port <= 65535.
// (DEPENDS-ON)  ANN-4d1b82fa, ANN-c9e05a31
// (AGENT)       Generator
// (VERIFIED)    false
// (ROUND)       0
func parseAddress(raw string) (host string, port int, err error) {

Go — after Reviewer pass, Round 1 (violations found):

// [ANN]
// (ANN-ID)      ANN-7f3a9c2e
// (ORIGIN)      FR-0003, NFR-0001
// (TASK)        Parse IMAP server address and validate format.
// (CONTEXT)     Called once at startup before any connection is attempted.
// (CONSTRAINT)  Address must include host and port; scheme is not validated.
// (PRE)         raw is a non-empty string.
// (INPUT)       raw string — address as provided by the caller
// (OUTPUT)      host string — validated hostname or IP
// (OUTPUT)      port int    — validated port number
// (POST)        host is non-empty; 1 <= port <= 65535.
// (AGENT)       Reviewer
// (VERIFIED)    false
// (ROUND)       1
// (FINDING:1)   PRE declares raw is non-empty but no guard exists; empty string reaches net.SplitHostPort.
// (SEVERITY:1)  High
// (HINT:1)      Add guard: if len(raw) == 0 { return "", 0, ErrEmptyAddress }.
// (FINDING:2)   ORIGIN omits NFR-0001; function also enforces input-validation policy defined there.
// (SEVERITY:2)  Low
// (HINT:2)      Append NFR-0001 to (ORIGIN).
func parseAddress(raw string) (host string, port int, err error) {

Go — after Refiner pass, Round 1 (all findings resolved):

// [ANN]
// (ANN-ID)      ANN-7f3a9c2e
// (ORIGIN)      FR-0003, NFR-0001
// (TASK)        Parse IMAP server address and validate format.
// (CONTEXT)     Called once at startup before any connection is attempted.
// (CONSTRAINT)  Address must include host and port; scheme is not validated.
// (PRE)         raw is a non-empty string.
// (INPUT)       raw string — address as provided by the caller
// (OUTPUT)      host string — validated hostname or IP
// (OUTPUT)      port int    — validated port number
// (POST)        host is non-empty; 1 <= port <= 65535.
// (AGENT)       Refiner
// (VERIFIED)    true
// (ROUND)       1
// (FINDING:1)   PRE declares raw is non-empty but no guard exists; empty string reaches net.SplitHostPort.
// (SEVERITY:1)  High
// (HINT:1)      Add guard: if len(raw) == 0 { return "", 0, ErrEmptyAddress }.
// (FINDING:1:STATUS)  Resolved — empty-string guard added before net.SplitHostPort call
// (FINDING:2)   ORIGIN omits NFR-0001; function also enforces input-validation policy defined there.
// (SEVERITY:2)  Low
// (HINT:2)      Append NFR-0001 to (ORIGIN).
// (FINDING:2:STATUS)  Resolved — NFR-0001 appended to (ORIGIN)
func parseAddress(raw string) (host string, port int, err error) {

Go — Refiner amended a descriptive field (FIELD-CHANGE example):

// [ANN]
// (ANN-ID)      ANN-7f3a9c2e
// (ORIGIN)      FR-0003, NFR-0001
// (TASK)        Parse IMAP server address and validate format.
// (CONTEXT)     Called once at startup before any connection is attempted.
// (CONSTRAINT)  Address must include host and port; scheme is not validated.
// (PRE)         raw is a non-empty string and contains exactly one colon.
// (FIELD-CHANGE:1)  (PRE) amended — added "and contains exactly one colon" to match guard added for FINDING:1
// (INPUT)       raw string — address as provided by the caller
// ...

Python:

# [ANN]
# (ANN-ID)      ANN-4d1b82fa
# (ORIGIN)      FR-0003, NFR-0001
# (TASK)        Parse IMAP server address and validate format.
# (CONTEXT)     Called once at startup before any connection is attempted.
# (CONSTRAINT)  Address must include host and port; scheme is not validated.
# (PRE)         raw is a non-empty string.
# (INPUT)       raw: str — address as provided by the caller
# (OUTPUT)      tuple[str, int] — validated (host, port)
# (POST)        host is non-empty; 1 <= port <= 65535.
# (AGENT)       Generator
# (VERIFIED)    false
# (ROUND)       0
def parse_address(raw: str) -> tuple[str, int]:

Java:

/* [ANN]
 * (ANN-ID)      ANN-c9e05a31
 * (ORIGIN)      FR-0003, NFR-0001
 * (TASK)        Parse IMAP server address and validate format.
 * (CONTEXT)     Called once at startup before any connection is attempted.
 * (CONSTRAINT)  Address must include host and port; scheme is not validated.
 * (PRE)         raw is non-null and non-empty.
 * (INPUT)       raw String — address as provided by the caller
 * (OUTPUT)      InetSocketAddress — validated host/port pair
 * (POST)        Result host is non-empty; 1 <= port <= 65535.
 * (AGENT)       Generator
 * (VERIFIED)    false
 * (ROUND)       0
 */
public InetSocketAddress parseAddress(String raw) {

Annotation mutation rules

Agents must not modify [ANN] blocks beyond these permitted actions:

Agent Permitted actions
Generator Write the entire block (initial creation only); generate (ANN-ID); write (DEPENDS-ON)
Reviewer Update (AGENT), (VERIFIED), (ROUND); append (FINDING:n), (SEVERITY:n), (HINT:n)
Refiner Update (AGENT), (VERIFIED), (ROUND); append (FINDING:n:STATUS), (FIELD-CHANGE:n); update descriptive fields only when they become factually incorrect after a code fix
SecurityAuditor Same as Reviewer for (CONSTRAINT:SEC) violations
TestGenerator Write entire block on test functions (TDD mode only); set (TEST-MODE) TDD; otherwise read-only
Analyzer Write the entire block (initial creation on existing code); generate (ANN-ID); write (CONFIDENCE)
Transformation Write the entire block on transformed code; preserve (ANN-ID) per split/merge rules; may not modify (ANN-ID) beyond those rules; write (DEPENDS-ON)
Architect Does not write [ANN] blocks; writes only UTF-8 Markdown under sdais/adf/v<N>/
Grounder Does not write [ANN] blocks; writes only **Verified:** fields in E- item files and appends findings to those files

(ANN-ID) is written only by Generator and Analyzer at block creation time. No other agent may modify (ANN-ID) under any circumstance, except Transformation applying the split/merge rules. Finding labels are never removed or renumbered. (FINDING:n:STATUS) is appended directly after the (HINT:n) for the same index.


Syntax Table

Core Labels (from Design by Contract heritage)

Label Cardinality Scope Description
(ANN-ID) exactly 1 (1–n for merged units) all Stable unique identifier in the form ANN-<8-hex>. Generated once at block creation by Generator or Analyzer. No agent may modify it except Transformation applying split/merge rules. Must appear as the first label in the block.
(TASK) exactly 1 all Declarative statement of what this unit does
(CONTEXT) 0–1 all Where and why this unit is used; inherited from outer scope if absent
(CONSTRAINT) 0–n all Hard rule, invariant, or limit that applies to this unit
(CONSTRAINT:PERF) 0–n all Performance bound (latency, throughput, memory)
(CONSTRAINT:SEC) 0–n all Security classification or access control rule
(CONSTRAINT:AVAIL) 0–n all Availability or fault-tolerance expectation
(CONSTRAINT:CONSIST) 0–n all Data consistency or transactional requirement
(CONSTRAINT:COMPAT) 0–n all API, platform, or runtime compatibility requirement
(PRE) 0–n function / method Condition that must hold before execution
(INPUT) 0–n function / method Named input: name type — description
(OUTPUT) 0–n function / method Named output: name type — description
(POST) 0–n function / method Condition that must hold after execution

Structural Labels

Label Cardinality Scope Written by Description
(DEPENDS-ON) 0–n function / method, type Generator, Transformation Comma-separated ANN-<8-hex> IDs of units this unit directly calls or structurally requires. Omitted when there are no dependencies. Format: ANN-4d1b82fa, ANN-c9e05a31
(TEST-MODE) 0–1 function / method TestGenerator Value: TDD. Set on every test function block produced in TDD mode. Absent on all standard test annotations and on all implementation annotations.

SDAIS Traceability Labels

Label Cardinality Scope Description
(ORIGIN) 1–n all RSF requirement ID(s) this unit implements (e.g. FR-0002, NFR-0001)
(AGENT) exactly 1 all Role of the agent that last wrote or modified this block
(VERIFIED) exactly 1 all true — review agent confirmed; false — pending or violation flagged
(ROUND) exactly 1 all Integer; the review round in which this block was last written or updated
(CONFIDENCE) 0–1 all Written by Analyzer (on [ANN] blocks) and TransformationEngineer (on TRS items). Values: Inferred-High, Inferred-Medium, or Inferred-Low on ANN blocks; High, Medium, or Low on TRS items. Absent on greenfield-generated annotations.

Review Finding Labels

Written by the Reviewer (or SecurityAuditor) into the [ANN] block of any unit where (VERIFIED) is false. Labels are co-indexed: (FINDING:n), (SEVERITY:n), and (HINT:n) with the same n describe one finding. n is a 1-based integer local to the block and is never reused across rounds. After the Refiner acts, (FINDING:n:STATUS) is appended immediately after (HINT:n).

Label Cardinality Written by Description
(FINDING:n) 0–n Reviewer Describes one specific violation in this block
(SEVERITY:n) paired Reviewer Critical / High / Medium / Low — paired with the same-indexed FINDING
(HINT:n) paired Reviewer Actionable instruction for the Refiner to resolve the paired FINDING
(FINDING:n:STATUS) 0–n Refiner / Human Resolved — <rationale> or Waived — requires RSF amendment
(FIELD-CHANGE:n) 0–n Refiner Documents which descriptive field was changed and why; n matches the FINDING

Agent Role Values (for (AGENT))

Value Description
RequirementsEngineer Clarification and RSF derivation from free-form prose in sdais/gspec/
TransformationEngineer Clarification and TRS/CDF derivation from free-form prose in sdais/tspec/
Generator Initial synthesis from RSF
Reviewer Validation pass; sets (VERIFIED) and writes finding labels
Refiner Corrects violations directed by (HINT:n); writes (FINDING:n:STATUS)
SecurityAuditor Specialised pass for (CONSTRAINT:SEC) compliance; may write finding labels
TestGenerator Derives tests from (PRE), (POST), and acceptance criteria; in TDD mode, produces pre-implementation test stubs
SemanticAuditor RSF-level semantic validation before generation; appends findings to RSF files
Analyzer Transformation: annotates existing codebase; derives RSF items; appends findings to RSF files
Transformation Transformation: applies CDF transformations; preserves (ANN-ID) values
Architect Produces the ADF document set from cleared RSF; runs between infrastructure grounding and generation
Grounder Verifies infrastructure assumptions in E- items before generation; appends ENV-UNRESOLVABLE findings to E- item files

Scope Levels

Level Applies to Typical labels present
Library Top-level package / module root (ANN-ID), (TASK), (CONTEXT), (CONSTRAINT), (ORIGIN)
Package Sub-package or namespace (ANN-ID), (TASK), (CONTEXT), (CONSTRAINT), (ORIGIN)
Type / Class Struct, class, interface, enum (ANN-ID), (TASK), (CONSTRAINT), (ORIGIN)
Function / Method Any callable unit All labels

Finding Categories

Findings are appended to RSF item files in ## Findings sections. The SemanticAuditor, Grounder, and Analyzer agents each assign one of the following categories:

Category Written by Description
AMBIGUOUS SemanticAuditor Requirement is not precise enough for deterministic synthesis
INCOMPLETE SemanticAuditor An FR has no corresponding AC, or an AC does not verify its FR
CONTRADICTORY SemanticAuditor RSF items or adopted library contracts are mutually exclusive
INFEASIBLE SemanticAuditor A constraint makes one or more FRs impossible to satisfy
UNTESTABLE SemanticAuditor An acceptance criterion cannot be verified programmatically
UNQUANTIFIED SemanticAuditor An NFR lacks a measurable bound
LIBRARY-UNRESOLVABLE SemanticAuditor A Libraries entry is malformed, missing, unreadable, unversioned, escapes the library root, or names a missing heading anchor
TRS-CONTRADICTS-CODE Analyzer (SDAIS-T) A hypothesis from the TRS is contradicted by what the code actually does
CODE-INTENT-UNCLEAR Analyzer (SDAIS-T) Code behaviour cannot be unambiguously mapped to a specific requirement
ENV-UNRESOLVABLE Grounder An E- item names an infrastructure element that cannot be confirmed to exist or match its description

RSF Individual File Format

# <TYPE>-NNNN: Short Title

- **Type:** Functional Requirement | Non-Functional Requirement | Constraint | Environment | Acceptance Criterion
- **Status:** Active | Dropped | Superseded | Split
- **Introduced:** v<N> (<YYYY-MM-DD>)
- **Last modified:** v<N> (<YYYY-MM-DD>)
- **Source:** sdais/gspec/v<N>/filename.md  ← omit when item was authored directly without Step −2
- **Libraries:** sdais/library/<library-id>/v<N>/<file>[#<anchor>]  ← optional; comma-separated
- **Verified:** Pending | true    ← Environment items only; omitted for all other types

## Requirement

<Precise, testable statement of the requirement.>

Related: [FR-NNNN], [NFR-NNNN], [AC-NNNN]

—

## Findings

(appended by SemanticAuditor, Grounder, or Analyzer when this item has findings)

### F1: <Short title of finding>

- **Category:** AMBIGUOUS | INCOMPLETE | CONTRADICTORY | INFEASIBLE | UNTESTABLE | UNQUANTIFIED | LIBRARY-UNRESOLVABLE | TRS-CONTRADICTS-CODE | CODE-INTENT-UNCLEAR | ENV-UNRESOLVABLE
- **Severity:** Critical | High | Medium | Low
- **References:** [RSF-<TYPE>-NNNN-V<N>], …

<Precise description of the problem.>

<Resolution block: Variants (SemanticAuditor) or Hint + Resolution (Grounder,
Analyzer) — see Findings Appendix Format.>

Header fields (and the Category/Severity/References block of each finding) are written as list items. Consecutive plain **Field:** value lines form a single Markdown paragraph and run together in previewers; one list item per field keeps them on separate lines. The same applies to every SDAIS artefact with a field header — TRS items, CDFs, ADFs, and custom agent definitions.

Libraries is optional on every RSF type. When present it follows Source, or Last modified if Source is absent. Every entry is a concrete, exact-version file path under sdais/library/, optionally with a heading anchor. Legacy files without the field remain valid.


Findings Appendix Format

Findings are appended to RSF item files by the SemanticAuditor, Grounder, and Analyzer agents. They appear after a — separator as a ## Findings section within the staged copy of the RSF file in sdais/rsf/v<N+1>/. Finding numbers are local to each RSF item file, starting at 1 and incrementing across audit rounds.

Every finding opens the same way — title, field list, description — and closes with a resolution block whose form depends on the agent.

SemanticAuditor findings close with solution variants. The agent writes two to four variants, each a complete resolution that clears the finding once applied; a fixed Own line follows for anything the variants miss. The human ticks exactly one box and replaces every {{placeholder}} in the ticked line.

—

## Findings

### F1: Processing Time Bound Lacks a Measurement Basis

- **Category:** UNQUANTIFIED
- **Severity:** Medium
- **References:** [RSF-NFR-0001-V1], [RSF-AC-0010-V1]

NFR-0001 bounds processing time per row but states neither the hardware nor
what is timed, so AC-0010 cannot be checked reproducibly.

**Variants** — tick exactly one `[x]` and replace every `{{placeholder}}` in it:

- [ ] **V1 — Fix** (recommended): The system must process a {{file_size_mb}} MB CSV file in at most {{max_seconds}} s wall-clock time, measured end to end from process start to exit on {{reference_hardware}}.
- [ ] **V2 — Fix:** The system must sustain a throughput of at least {{min_rows_per_second}} rows per second, measured over a file of at least 1,000,000 rows on {{reference_hardware}}, excluding process startup.
- [ ] **V3 — Drop:** Performance is not a requirement for this tool; remove NFR-0001 and AC-0010.
- [ ] **Own:** {{your_resolution}}
  • Variant actions are Fix, Drop, Supersede, Split, and Waive, as in Step 0.2. For Fix, Supersede, and Split the variant text is the exact replacement ## Requirement text, ready to paste.
  • {{snake_case}} placeholders mark only details the human must supply: numbers, units, names, and choices the specification leaves open. Anything derivable from the RSF is written out. Double braces, not angle brackets: Markdown previewers treat <rationale> as an unknown HTML tag and render nothing.
  • V1 is the auditor's recommendation. The agent never ticks a box.

Grounder and Analyzer findings close with a hint and a resolution field:

**Hint:** <Concrete, actionable instruction for the human author to resolve this
finding. Be specific about what text to add, remove, or change.>

**Resolution:**
(filled in by human after review)

Reference syntax: [RSF-<TYPE>-NNNN-V<N>] identifies a specific RSF item at a specific version. Example: [RSF-FR-0003-V1] = FR-0003 as it existed in RSF v1.


Template Files

The 0000 files in sdais/rsf/v1/ are inert scaffolds. They are never processed by any agent. To author a new item, copy the relevant template, rename it with the next available sequence number and a short description, and replace every bracketed placeholder with real content.

sdais/rsf/v1/fr-0000-template.md

# FR-0000: [Short title of the functional requirement]

- **Type:** Functional Requirement
- **Status:** Template
- **Introduced:** v1 (YYYY-MM-DD)
- **Last modified:** v1 (YYYY-MM-DD)
- **Source:** [sdais/gspec/v<N>/filename.md — omit if item was authored directly]
- **Libraries:** [sdais/library/<library-id>/v<N>/<file> — optional; comma-separated]

## Requirement

[Precise, testable statement of what the system must do. Begin with "The system
must" or "The <component> must". Describe observable behaviour, not implementation
detail. Every FR must have at least one corresponding AC.]

Related: [Cross-references to related items, e.g. [NFR-0001], [AC-0001]. Omit section if none.]

sdais/rsf/v1/nfr-0000-template.md

# NFR-0000: [Short title of the non-functional requirement]

- **Type:** Non-Functional Requirement
- **Status:** Template
- **Introduced:** v1 (YYYY-MM-DD)
- **Last modified:** v1 (YYYY-MM-DD)
- **Source:** [sdais/gspec/v<N>/filename.md — omit if item was authored directly]
- **Libraries:** [sdais/library/<library-id>/v<N>/<file> — optional; comma-separated]

## Requirement

[Measurable quality attribute the system must satisfy. Include a numeric bound,
e.g. "95th-percentile latency must not exceed 200 ms under a load of 1 000
concurrent requests". Unquantified NFRs are flagged UNQUANTIFIED by the
SemanticAuditor.]

Related: [Cross-references to related items. Omit section if none.]

sdais/rsf/v1/c-0000-template.md

# C-0000: [Short title of the constraint]

- **Type:** Constraint
- **Status:** Template
- **Introduced:** v1 (YYYY-MM-DD)
- **Last modified:** v1 (YYYY-MM-DD)
- **Source:** [sdais/gspec/v<N>/filename.md — omit if item was authored directly]
- **Libraries:** [sdais/library/<library-id>/v<N>/<file> — optional; comma-separated]

## Requirement

[Hard rule that narrows the solution space without describing a feature.
Examples: "The implementation must use Go 1.22 or later", "No third-party
cryptographic libraries may be used".]

Related: [Cross-references to related items. Omit section if none.]

sdais/rsf/v1/e-0000-template.md

# E-0000: [Short title of the environment item]

- **Type:** Environment
- **Status:** Template
- **Introduced:** v1 (YYYY-MM-DD)
- **Last modified:** v1 (YYYY-MM-DD)
- **Source:** [sdais/gspec/v<N>/filename.md — omit if item was authored directly]
- **Libraries:** [sdais/library/<library-id>/v<N>/<file> — optional; comma-separated]
- **Verified:** Pending

## Requirement

[Description of the runtime or deployment environment the system must operate
in. Examples: "The service will be deployed as a single binary on Linux/amd64
hosts running kernel 5.15 or later", "The system will have access to a
PostgreSQL 15 instance at the address given by the DATABASE_URL environment
variable".]

Related: [Cross-references to related items. Omit section if none.]

sdais/rsf/v1/ac-0000-template.md

# AC-0000: [Short title of the acceptance criterion]

- **Type:** Acceptance Criterion
- **Status:** Template
- **Introduced:** v1 (YYYY-MM-DD)
- **Last modified:** v1 (YYYY-MM-DD)
- **Source:** [sdais/gspec/v<N>/filename.md — omit if item was authored directly]
- **Libraries:** [sdais/library/<library-id>/v<N>/<file> — optional; comma-separated]

## Requirement

[Concrete, programmatically verifiable condition that confirms one or more FRs
are satisfied. Specify inputs, expected outputs, and observable side-effects.
Every FR must be covered by at least one AC. Criteria that cannot be verified
programmatically are flagged UNTESTABLE by the SemanticAuditor.]

Related: [Cross-references to the FR(s) this criterion verifies, e.g. [FR-0001].]