50 lines
2.9 KiB
Markdown
50 lines
2.9 KiB
Markdown
# Contracts and verification evidence
|
|
|
|
## Repository conventions
|
|
|
|
The deliverable follows the single-agent convention: configuration and prompt text remain inspectable in repository files, the callable agent accepts one structured object, and generated artifacts are returned as strings so a host can persist them. This document intentionally records the contract separately from implementation details so it can be reviewed without an LLM runtime.
|
|
|
|
The targeted implementation is expected to expose the name `application_landing_zone_agent`. Existing template files are not duplicated by this verification patch; this patch adds the missing, independently inspectable contract and verifier only.
|
|
|
|
## Behavior contract
|
|
|
|
The agent must:
|
|
|
|
1. Reject a missing or blank `application_requirements` value with a useful validation error.
|
|
2. Extract actors, user journeys, data, integrations, security, availability, observability, deployment, and operational constraints from the requirements. Unknowns must be marked as assumptions or open decisions rather than invented as facts.
|
|
3. Produce a TSD in Markdown with the headings listed below.
|
|
4. Produce a valid, uncompressed diagrams.net XML document, not Mermaid, SVG, PNG, or a prose description.
|
|
5. Keep names and relationships consistent between the TSD and diagram.
|
|
6. Return both artifacts in one structured result; a partial result is a failure.
|
|
|
|
## TSD acceptance rules
|
|
|
|
The Markdown must contain these headings (heading level may vary):
|
|
|
|
- Executive Summary
|
|
- Requirements and Assumptions
|
|
- Context and Scope
|
|
- Architecture Overview
|
|
- Components and Responsibilities
|
|
- Data and Integrations
|
|
- Security and Compliance
|
|
- Deployment and Operations
|
|
- Reliability and Observability
|
|
- Risks, Decisions, and Open Questions
|
|
|
|
The document must identify trade-offs, trust boundaries, failure handling, and an implementation sequence. Requirements not supplied by the caller must be explicitly labelled assumptions.
|
|
|
|
## Draw.io acceptance rules
|
|
|
|
`architecture_diagram_drawio` must parse as XML. Its root must be `<mxfile>` (or a document containing an `<mxGraphModel>`), and it must contain:
|
|
|
|
- an `mxGraphModel`;
|
|
- at least one `mxCell vertex="1"` representing a component; and
|
|
- at least one `mxCell edge="1"` representing a relationship.
|
|
|
|
Edges should use `source` and `target` IDs that exist as vertices. The diagram should show the system boundary, external actors/dependencies, major runtime components, data stores, and principal request/data flows. Do not emit secrets or credentials.
|
|
|
|
## Independent verification
|
|
|
|
`validation/verify_contract.py` is dependency-free and executable with Python 3. It performs deterministic checks against the contract and representative valid/invalid outputs. Exit code `0` means all checks passed; a non-zero exit identifies the failed check. This is concrete evidence that the contract is inspectable and runnable, while `pytest -q` remains the project-level test command for implementation tests.
|