- Date: 2026-10-08
- Version: v0.13.0
- Status: Draft
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.
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.
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.
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.
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 |
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.
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 intogspec/v1/; the agent createsgspec/v2/with lightweight[[Q1]]inline markers and a## Questionssection per file; the human answers ingspec/v2/by writing free prose below each### QN:heading; the agent createsgspec/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 togspec/: immutable snapshots, inline[[QN]]markers and per-file## Questionssections, 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## Findingssections within the staged copies inrsf/v<N+1>/. - Each
trs/v<N>/directory contains TRS items introduced or amended in version N. Version semantics match those ofrsf/. - 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 underdecisions/. The five core filenames carryadf-01-throughadf-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 createv<N+1>/. The entirelibrary/directory may be absent or empty when no requirement uses it. - The distribution is
sdais-vX.Y.Z.tgz. It containsSDAIS.md,README.md,CHANGELOG.md,LICENSE,install.sh,update.sh,sdais.sh,docs/, andscaffold/, and expands directly into the current directory. Create a project root, copy or download the archive into it, runtar 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 byinstalland refreshed byupdate.
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.
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-coordinatesSource 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.
┌──────────────────────────────────────────────────────┐
│ 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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: DroppedorStatus: Superseded. - New items introduced during an amendment use the next available sequential number in their prefix group.
- 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.
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.
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
## Requirementsection 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## Findingssection and git history preserve the rationale). - Items that are Dropped or Superseded set
Status:accordingly and retain their## Requirementtext 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.
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
Approvedand every ADR status toAccepted; 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.
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.
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:
- 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. - 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. - Continue with the standard Review → Refine loop. The Reviewer additionally verifies that all
(TEST-MODE) TDDblocks pass against the generated implementation.
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.
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) falsedue to Resolved findings (not Waived): run the Reviewer again at round N+1. - If all remaining
(VERIFIED) falseblocks have only Waived findings: the human amends the RSF (new version), then returns to Step 0.
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.
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.
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.
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.
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.
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.
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/.
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.
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.
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:**fromDrafttoActive.
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.
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 |
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.
The Analyzer operates in three-output mode:
-
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 outsideimplementation/. Where a TRS item ID maps confidently to a unit,(ORIGIN)is set to that TRS item ID. -
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. -
Appends findings to RSF item files staged in
sdais/rsf/v<N+1>/for any unclear mappings, using the transformation finding categoriesTRS-CONTRADICTS-CODEandCODE-INTENT-UNCLEAR.
The full prompt is in sdais/prompts/analyzer.md.
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)asANN-<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.
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.
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.
#### <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`- 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 withDOMAIN-. - Annotation Permissions: Same as Reviewer — appends finding labels; updates
(AGENT),(VERIFIED),(ROUND). - Prompt:
sdais/prompts/domain-auditor.md
- 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 withGDPR-. - Annotation Permissions: Same as SecurityAuditor — appends finding labels for
(CONSTRAINT:SEC)violations; updates(AGENT),(VERIFIED),(ROUND). - Prompt:
sdais/prompts/compliance-auditor-gdpr.md
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.
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) {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.
| 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 |
| 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. |
| 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. |
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 |
| 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 |
| 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 |
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 |
# <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 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, andWaive, as in Step 0.2. ForFix,Supersede, andSplitthe variant text is the exact replacement## Requirementtext, 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.V1is 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.
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.
# 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.]# 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.]# 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.]# 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.]# 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].]