@agent-ix/quoin 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/plugins/marketplace.json +14 -0
- package/.claude-plugin/marketplace.json +16 -0
- package/.claude-plugin/plugin.json +8 -0
- package/.codex-plugin/plugin.json +27 -0
- package/.github/plugin/marketplace.json +16 -0
- package/LICENSE +21 -0
- package/README.md +266 -0
- package/bin/quoin.js +14 -0
- package/default-modules.yaml +82 -0
- package/dist/base-DrUMkAh1.js +137 -0
- package/dist/base.d.ts +23 -0
- package/dist/base.d.ts.map +1 -0
- package/dist/catalog.d.ts +32 -0
- package/dist/catalog.d.ts.map +1 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +20 -0
- package/dist/commands/catalog/index.d.ts +2 -0
- package/dist/commands/catalog/index.d.ts.map +1 -0
- package/dist/commands/catalog/index.js +2 -0
- package/dist/commands/catalog/list.d.ts +11 -0
- package/dist/commands/catalog/list.d.ts.map +1 -0
- package/dist/commands/catalog/list.js +22 -0
- package/dist/commands/catalog/show.d.ts +13 -0
- package/dist/commands/catalog/show.d.ts.map +1 -0
- package/dist/commands/catalog/show.js +25 -0
- package/dist/commands/catalog/validate.d.ts +10 -0
- package/dist/commands/catalog/validate.d.ts.map +1 -0
- package/dist/commands/catalog/validate.js +27 -0
- package/dist/commands/config/doctor.d.ts +7 -0
- package/dist/commands/config/doctor.d.ts.map +1 -0
- package/dist/commands/config/doctor.js +15 -0
- package/dist/commands/config/edit.d.ts +7 -0
- package/dist/commands/config/edit.d.ts.map +1 -0
- package/dist/commands/config/edit.js +13 -0
- package/dist/commands/config/get.d.ts +11 -0
- package/dist/commands/config/get.d.ts.map +1 -0
- package/dist/commands/config/get.js +20 -0
- package/dist/commands/config/index.d.ts +2 -0
- package/dist/commands/config/index.d.ts.map +1 -0
- package/dist/commands/config/index.js +2 -0
- package/dist/commands/config/set.d.ts +12 -0
- package/dist/commands/config/set.d.ts.map +1 -0
- package/dist/commands/config/set.js +26 -0
- package/dist/commands/matrix.d.ts +14 -0
- package/dist/commands/matrix.d.ts.map +1 -0
- package/dist/commands/matrix.js +15 -0
- package/dist/commands/module/ensure-defaults.d.ts +8 -0
- package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
- package/dist/commands/module/ensure-defaults.js +17 -0
- package/dist/commands/module/index.d.ts +2 -0
- package/dist/commands/module/index.d.ts.map +1 -0
- package/dist/commands/module/index.js +2 -0
- package/dist/commands/module/install.d.ts +11 -0
- package/dist/commands/module/install.d.ts.map +1 -0
- package/dist/commands/module/install.js +22 -0
- package/dist/commands/module/list.d.ts +8 -0
- package/dist/commands/module/list.d.ts.map +1 -0
- package/dist/commands/module/list.js +13 -0
- package/dist/commands/module/remove.d.ts +10 -0
- package/dist/commands/module/remove.d.ts.map +1 -0
- package/dist/commands/module/remove.js +16 -0
- package/dist/commands/plugin/deprecation.d.ts +10 -0
- package/dist/commands/plugin/deprecation.d.ts.map +1 -0
- package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
- package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
- package/dist/commands/plugin/ensure-defaults.js +12 -0
- package/dist/commands/plugin/index.d.ts +2 -0
- package/dist/commands/plugin/index.d.ts.map +1 -0
- package/dist/commands/plugin/index.js +2 -0
- package/dist/commands/plugin/install.d.ts +8 -0
- package/dist/commands/plugin/install.d.ts.map +1 -0
- package/dist/commands/plugin/install.js +12 -0
- package/dist/commands/plugin/list.d.ts +8 -0
- package/dist/commands/plugin/list.d.ts.map +1 -0
- package/dist/commands/plugin/list.js +12 -0
- package/dist/commands/plugin/remove.d.ts +8 -0
- package/dist/commands/plugin/remove.d.ts.map +1 -0
- package/dist/commands/plugin/remove.js +12 -0
- package/dist/commands/review.d.ts +14 -0
- package/dist/commands/review.d.ts.map +1 -0
- package/dist/commands/review.js +15 -0
- package/dist/commands/to-plan.d.ts +14 -0
- package/dist/commands/to-plan.d.ts.map +1 -0
- package/dist/commands/to-plan.js +15 -0
- package/dist/commands/update.d.ts +13 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +34 -0
- package/dist/commands/write.d.ts +16 -0
- package/dist/commands/write.d.ts.map +1 -0
- package/dist/commands/write.js +33 -0
- package/dist/config-schema-Dp-vlxuR.js +13 -0
- package/dist/config-schema.d.ts +52 -0
- package/dist/config-schema.d.ts.map +1 -0
- package/dist/deprecation-fRxUHoxv.js +4 -0
- package/dist/flow-command-SMjCSOFg.js +88 -0
- package/dist/flow-command.d.ts +25 -0
- package/dist/flow-command.d.ts.map +1 -0
- package/dist/flows.d.ts +7 -0
- package/dist/flows.d.ts.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +9 -0
- package/dist/modules-CW8pBK41.js +22 -0
- package/dist/modules.d.ts +10 -0
- package/dist/modules.d.ts.map +1 -0
- package/dist/org.d.ts +61 -0
- package/dist/org.d.ts.map +1 -0
- package/dist/plugins-GSxafyD3.js +77 -0
- package/dist/plugins.d.ts +13 -0
- package/dist/plugins.d.ts.map +1 -0
- package/dist/version-_1nY4KyJ.js +17 -0
- package/dist/version.d.ts +3 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/write-CQAitcI5.js +156 -0
- package/dist/write.d.ts +28 -0
- package/dist/write.d.ts.map +1 -0
- package/package.json +119 -0
- package/skills/gap-analysis/SKILL.md +97 -0
- package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
- package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
- package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
- package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
- package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
- package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
- package/skills/spec-app-review/SKILL.md +51 -0
- package/skills/spec-app-review/references/checklist.md +197 -0
- package/skills/spec-dependency-analysis/SKILL.md +75 -0
- package/skills/spec-ears-analysis/SKILL.md +89 -0
- package/skills/spec-evidence-analysis/SKILL.md +78 -0
- package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
- package/skills/spec-ideation/SKILL.md +46 -0
- package/skills/spec-integrity-analysis/SKILL.md +47 -0
- package/skills/spec-matrix/SKILL.md +168 -0
- package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
- package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
- package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
- package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
- package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
- package/skills/spec-object-review/SKILL.md +125 -0
- package/skills/spec-object-review/references/object-type-guide.md +118 -0
- package/skills/spec-review/SKILL.md +71 -0
- package/skills/spec-review/references/checklist.md +50 -0
- package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
- package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
- package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
- package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
- package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
- package/skills/spec-security-analysis/SKILL.md +84 -0
- package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
- package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
- package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
- package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
- package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
- package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
- package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
- package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
- package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
- package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
- package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
- package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
- package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
- package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
- package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
- package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
- package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
- package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
- package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
- package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
- package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
- package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
- package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
- package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
- package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
- package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
- package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
- package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
- package/skills/spec-security-analysis/references/soc2/index.md +46 -0
- package/skills/spec-security-analysis/references/standards-index.md +46 -0
- package/skills/spec-to-plan/SKILL.md +75 -0
- package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
- package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
- package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
- package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
- package/skills/specify/SKILL.md +154 -0
- package/skills/specify/assets/app-spec-template.md +143 -0
- package/skills/specify/assets/spec-template.md +299 -0
- package/skills/specify/references/integration-tests.md +72 -0
- package/skills/specify/references/us-to-fr.md +40 -0
- package/skills/specify/references/writing-good-requirements.md +61 -0
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: master-requirements
|
|
3
|
+
name: <component-name> # Required: repo/component name
|
|
4
|
+
org: <your-org> # Required: owning org — use the `Org:` quoin write reports
|
|
5
|
+
component_type: fastapi-service # Canonical type (fastapi-service, react-lib, etc.)
|
|
6
|
+
tags: # Optional capabilities
|
|
7
|
+
- postgres
|
|
8
|
+
- redis
|
|
9
|
+
implementation_language: python
|
|
10
|
+
depends_on: [] # Direct package/service dependencies
|
|
11
|
+
relationships: # Structured array of semantic cross-references
|
|
12
|
+
- target: "ix://org/repo/<dependency-name>"
|
|
13
|
+
type: "depends_on"
|
|
14
|
+
cardinality: "1:1"
|
|
15
|
+
|
|
16
|
+
standards_alignment:
|
|
17
|
+
- iso-iec-ieee-29148
|
|
18
|
+
- ieee-828
|
|
19
|
+
---
|
|
20
|
+
# Master Requirements Specification
|
|
21
|
+
## <Project Name>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 1. Purpose
|
|
26
|
+
|
|
27
|
+
This document defines the **scope, intent, and governing requirements framework** for the <Project Name> Python state machine library.
|
|
28
|
+
|
|
29
|
+
It establishes:
|
|
30
|
+
- The problem space addressed by the library
|
|
31
|
+
- The boundaries of responsibility
|
|
32
|
+
- The authoritative structure for requirements, verification, and change control
|
|
33
|
+
- The relationship between user intent, system behavior, and test evidence
|
|
34
|
+
|
|
35
|
+
This document is the **top-level requirements artifact** for the repository.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 2. Scope
|
|
40
|
+
|
|
41
|
+
### 2.1 In Scope
|
|
42
|
+
|
|
43
|
+
This specification governs:
|
|
44
|
+
- Core state machine behavior
|
|
45
|
+
- State lifecycle management
|
|
46
|
+
- Transition rules and validation
|
|
47
|
+
- Event handling semantics
|
|
48
|
+
- Error and failure handling behavior
|
|
49
|
+
- Public APIs that affect observable behavior
|
|
50
|
+
- Deterministic execution guarantees
|
|
51
|
+
|
|
52
|
+
### 2.2 Out of Scope
|
|
53
|
+
|
|
54
|
+
This specification does not govern:
|
|
55
|
+
- Application-specific business logic
|
|
56
|
+
- UI or visualization layers
|
|
57
|
+
- Deployment concerns
|
|
58
|
+
- Integrations beyond defined interfaces
|
|
59
|
+
- Experimental or prototype features not promoted to requirements
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 3. System Overview
|
|
64
|
+
|
|
65
|
+
### 3.1 System Description
|
|
66
|
+
|
|
67
|
+
<High-level description of the Python state machine library, its purpose, and the problems it solves.>
|
|
68
|
+
|
|
69
|
+
### 3.2 Intended Users
|
|
70
|
+
|
|
71
|
+
- <Library consumers>
|
|
72
|
+
- <Framework integrators>
|
|
73
|
+
- <Tooling or platform developers>
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## 4. Requirements Architecture
|
|
78
|
+
|
|
79
|
+
Requirements are decomposed and managed using a **hierarchical structure** consistent with ISO/IEC/IEEE 29148.
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
spec/
|
|
83
|
+
├── spec.md # This document (master specification)
|
|
84
|
+
├── stakeholder/ # Stakeholder requirements (StR-XXX)
|
|
85
|
+
├── usecase/ # User intent and usage scenarios (US-XXX)
|
|
86
|
+
├── functional/ # System / functional requirements (FR-XXX)
|
|
87
|
+
├── non-functional/ # Non-functional requirements (NFR-XXX)
|
|
88
|
+
├── tests.md # Bidirectional requirements ↔ tests mapping
|
|
89
|
+
├── test_cases/ # Verification artifacts (TC-XXX)
|
|
90
|
+
├── assets/
|
|
91
|
+
├── diagrams/ # State diagrams, sequence diagrams
|
|
92
|
+
├── models/ # Formal state and data models
|
|
93
|
+
└── poc/ # Explicitly requested proof-of-concepts
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 5. Requirement Classes
|
|
99
|
+
|
|
100
|
+
### 5.1 Stakeholder Requirements
|
|
101
|
+
|
|
102
|
+
Stakeholder Requirements capture **authoritative needs and expectations**.
|
|
103
|
+
|
|
104
|
+
- Format: `StR-XXX`
|
|
105
|
+
- Location: `stakeholder/`
|
|
106
|
+
- Nature: Normative for intent
|
|
107
|
+
- Purpose: Drive system requirements
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
### 5.2 User Requirements
|
|
112
|
+
|
|
113
|
+
User Stories describe **intent, expectations, and usage outcomes**.
|
|
114
|
+
|
|
115
|
+
- Format: `US-XXX`
|
|
116
|
+
- Location: `usecase/`
|
|
117
|
+
- Nature: Informational, non-binding
|
|
118
|
+
- Purpose: Drive functional requirements
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
### 5.3 Functional Requirements
|
|
123
|
+
|
|
124
|
+
Functional Requirements define **authoritative, testable system behavior**.
|
|
125
|
+
|
|
126
|
+
- Format: `FR-XXX`
|
|
127
|
+
- Location: `functional/`
|
|
128
|
+
- Nature: Normative and binding
|
|
129
|
+
- Purpose: Define observable behavior
|
|
130
|
+
|
|
131
|
+
All functional requirements:
|
|
132
|
+
- Use deterministic language
|
|
133
|
+
- Are independently testable
|
|
134
|
+
- Trace back to one or more user requirements
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
### 5.4 Non-Functional Requirements
|
|
139
|
+
|
|
140
|
+
Non-Functional Requirements define **quality constraints** (performance, security, etc.).
|
|
141
|
+
|
|
142
|
+
- Format: `NFR-XXX`
|
|
143
|
+
- Location: `non-functional/`
|
|
144
|
+
- Nature: Normative and binding
|
|
145
|
+
- Purpose: Constrain system qualities
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
### 5.5 Acceptance Criteria
|
|
150
|
+
|
|
151
|
+
Acceptance criteria define **verifiable outcomes** for functional requirements.
|
|
152
|
+
|
|
153
|
+
- Format: `{FR-XXX}-AC-N`
|
|
154
|
+
- Location: Within each functional requirement file
|
|
155
|
+
- Purpose: Verification anchor
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 6. Requirement Identification
|
|
160
|
+
|
|
161
|
+
### 6.1 Identifier Schema
|
|
162
|
+
|
|
163
|
+
| Artifact | Format | Example |
|
|
164
|
+
|-------|-------|--------|
|
|
165
|
+
| Stakeholder Requirement | `StR-XXX` | `StR-001` |
|
|
166
|
+
| User Story | `US-XXX` | `US-002` |
|
|
167
|
+
| Functional Requirement | `FR-XXX` | `FR-014` |
|
|
168
|
+
| Non-Functional Requirement | `NFR-XXX` | `NFR-003` |
|
|
169
|
+
| Acceptance Criteria | `{FR}-AC-N` | `FR-014-AC-1` |
|
|
170
|
+
| Test Case | `TC-XXX` | `TC-021` |
|
|
171
|
+
| Change Request | `CR-XXX` | `CR-009` |
|
|
172
|
+
|
|
173
|
+
Identifiers are immutable once assigned.
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## 7. Requirement Quality Policy
|
|
178
|
+
|
|
179
|
+
All **functional requirements** SHALL:
|
|
180
|
+
- Define observable behavior
|
|
181
|
+
- Be unambiguous and atomic
|
|
182
|
+
- Avoid implementation details unless required
|
|
183
|
+
- Be testable through explicit criteria
|
|
184
|
+
|
|
185
|
+
Functional requirements SHALL NOT:
|
|
186
|
+
- Encode application-specific policy
|
|
187
|
+
- Contain compound behaviors
|
|
188
|
+
- Use subjective language
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 8. State and Execution Model
|
|
193
|
+
|
|
194
|
+
### 8.1 State Semantics
|
|
195
|
+
|
|
196
|
+
<System-wide definition of what constitutes a state, terminal state, and transitional state.
|
|
197
|
+
Each managed lifecycle SHALL have a corresponding FR with `domain: state_machine`
|
|
198
|
+
in `spec/functional/` providing the canonical parseable definition.>
|
|
199
|
+
|
|
200
|
+
### 8.2 Transition Semantics
|
|
201
|
+
|
|
202
|
+
<System-wide rules for valid transitions, guards, and invalid transitions.>
|
|
203
|
+
|
|
204
|
+
### 8.3 Determinism Guarantees
|
|
205
|
+
|
|
206
|
+
<Statements about execution order, determinism, and concurrency assumptions.>
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## 9. Events and Signals
|
|
211
|
+
|
|
212
|
+
### 9.1 Event Model
|
|
213
|
+
|
|
214
|
+
<Overview of domain events. Each service SHALL have at least one event catalog FR
|
|
215
|
+
with `domain: event` in `spec/functional/` defining canonical event types and schemas.>
|
|
216
|
+
|
|
217
|
+
### 9.2 Event Guarantees
|
|
218
|
+
|
|
219
|
+
- Ordering guarantees
|
|
220
|
+
- Delivery guarantees
|
|
221
|
+
- Failure semantics
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 10. Error and Failure Model
|
|
226
|
+
|
|
227
|
+
### 10.1 Error Classification
|
|
228
|
+
|
|
229
|
+
- Configuration errors
|
|
230
|
+
- Runtime execution errors
|
|
231
|
+
- Invalid transition attempts
|
|
232
|
+
|
|
233
|
+
### 10.2 Failure Handling Guarantees
|
|
234
|
+
|
|
235
|
+
<System-wide expectations for error propagation, recovery, and reporting.>
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 11. Traceability
|
|
240
|
+
|
|
241
|
+
Bidirectional traceability SHALL be maintained between:
|
|
242
|
+
- Stakeholder Requirements → User Stories / Functional Requirements
|
|
243
|
+
- User Requirements → Functional Requirements
|
|
244
|
+
- Functional Requirements → Acceptance Criteria
|
|
245
|
+
- Acceptance Criteria → Test Cases
|
|
246
|
+
|
|
247
|
+
Traceability is recorded in `traceability_matrix.md`.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## 12. Verification Strategy
|
|
252
|
+
|
|
253
|
+
Functional requirements SHALL be verified using one or more of:
|
|
254
|
+
- Automated tests
|
|
255
|
+
- Manual tests
|
|
256
|
+
- Analysis
|
|
257
|
+
- Inspection
|
|
258
|
+
|
|
259
|
+
Verification evidence SHALL reference test cases in `test_cases/`.
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## 13. Change Management
|
|
264
|
+
|
|
265
|
+
All requirements artifacts are **configuration-controlled items**.
|
|
266
|
+
|
|
267
|
+
- Changes are proposed via change requests (`CR-XXX`)
|
|
268
|
+
- Changes require impact analysis
|
|
269
|
+
- Approved changes update affected requirements, tests, and traceability
|
|
270
|
+
- Historical versions are preserved
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## 14. Lifecycle Status
|
|
275
|
+
|
|
276
|
+
Functional requirements MAY declare a lifecycle status:
|
|
277
|
+
- DRAFT
|
|
278
|
+
- APPROVED
|
|
279
|
+
- IMPLEMENTED
|
|
280
|
+
- VERIFIED
|
|
281
|
+
- DEPRECATED
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## 15. Governance Notes
|
|
286
|
+
|
|
287
|
+
- This document defines **system intent**, not implementation
|
|
288
|
+
- Functional requirements SHALL precede code changes
|
|
289
|
+
- Proof-of-concept code SHALL only exist when explicitly requested
|
|
290
|
+
- Deprecated requirements SHALL be archived, not removed
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## 16. References
|
|
295
|
+
|
|
296
|
+
- ISO/IEC/IEEE 29148 — Requirements Engineering
|
|
297
|
+
- IEEE 828 — Configuration Management
|
|
298
|
+
|
|
299
|
+
---
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Authoring Integration Tests (IT)
|
|
2
|
+
|
|
3
|
+
Load this when a request involves integration tests — i.e. the system talks to
|
|
4
|
+
external services (HTTP APIs, event buses, databases, third-party/cloud APIs).
|
|
5
|
+
The per-section shape comes from the `IT` template (`quoin write --types IT`);
|
|
6
|
+
this file carries the *reasoning and reality rules* that the template can't
|
|
7
|
+
enforce.
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
HTTP client integrations, event bus connections (Kafka, RabbitMQ), database
|
|
12
|
+
connections (Postgres, Redis), and external APIs. One test case per file,
|
|
13
|
+
sequentially numbered (`IT-XXX`), saved to `spec/integration/IT-XXX-*.md`.
|
|
14
|
+
|
|
15
|
+
## Reality rules — REAL by default
|
|
16
|
+
|
|
17
|
+
> Integration tests are **ALWAYS REAL** by default. Nothing is mocked unless the
|
|
18
|
+
> spec explicitly says so. An IT that only checks imports or constructs models
|
|
19
|
+
> without exercising real behavior is a **GAP**.
|
|
20
|
+
|
|
21
|
+
Every IT MUST include acceptance criteria from **both** categories:
|
|
22
|
+
|
|
23
|
+
- **Real Setup ACs** — the non-mocked environment is established: service running
|
|
24
|
+
and healthy (real health endpoint), real dependencies available (DB, bus,
|
|
25
|
+
external service), fixtures loaded into real stores, config applied through real
|
|
26
|
+
loading paths.
|
|
27
|
+
- **Real Output ACs** — real output from real services: HTTP responses
|
|
28
|
+
(status/headers/body), DB state changes (rows inserted/updated/deleted), events
|
|
29
|
+
published to and consumed from a real bus, file-system state, SSE/WebSocket
|
|
30
|
+
streams, LLM responses through real provider chains.
|
|
31
|
+
|
|
32
|
+
| Real (required) | Not real (GAP) |
|
|
33
|
+
| ------------------------------------------------- | ------------------------------ |
|
|
34
|
+
| POST to endpoint, assert response body | `assert MyModel is not None` |
|
|
35
|
+
| Query DB after a write, verify rows changed | `MyModel(field="value")` |
|
|
36
|
+
| Publish event, consume from real bus, verify load | `assert EventSchema is not None` |
|
|
37
|
+
| GET /health, verify HTTP 200 + status body | `assert app is not None` |
|
|
38
|
+
|
|
39
|
+
### Mocking policy
|
|
40
|
+
|
|
41
|
+
- **Default: NO MOCKS.** ITs exercise real service boundaries.
|
|
42
|
+
- **Approved mock targets** only when the spec explicitly requires it: external
|
|
43
|
+
third-party APIs (payment, auth, cloud) via test doubles over real HTTP;
|
|
44
|
+
external services outside the test boundary via contract-faithful stubs.
|
|
45
|
+
- **Never mock**: HTTP transport, config loading, DB connections, file I/O,
|
|
46
|
+
session storage, event publishing, health endpoints, WebSocket/SSE connections.
|
|
47
|
+
- When a mock IS used, the IT must state WHY the real service can't be used, WHAT
|
|
48
|
+
boundary the mock replaces, and HOW the mock is verified faithful.
|
|
49
|
+
|
|
50
|
+
## Process
|
|
51
|
+
|
|
52
|
+
1. List the external dependencies from the codebase (the integration points).
|
|
53
|
+
2. Take the next `IT-XXX`; get the contract with `quoin write --types IT`.
|
|
54
|
+
3. Fill the template: Target Integration (service + protocol), Preconditions
|
|
55
|
+
(environment + data state), Test Data (`TD-XXX` fixtures with rationale),
|
|
56
|
+
Execution Plan (atomic steps, each with a timeout and `IT-XXX-SC-XX` success
|
|
57
|
+
criterion), Expected Outcome (success condition + failure modes).
|
|
58
|
+
4. **Traceability is required**: every IT links to ≥1 FR/StR/NFR via frontmatter
|
|
59
|
+
`relationships:` (`type: verifies`). Cross-component references are fine
|
|
60
|
+
(e.g. `ix://org/other-service/FR-001`) per ISO 29148 bidirectional traceability.
|
|
61
|
+
|
|
62
|
+
## Patterns by service type
|
|
63
|
+
|
|
64
|
+
- **API (FastAPI/REST)**: CRUD to real endpoints (verify codes/body/DB state);
|
|
65
|
+
invalid payloads → real 4xx; auth with/without creds → real 401/403.
|
|
66
|
+
- **Database**: real Alembic migrations → schema state; insert/query/update/delete
|
|
67
|
+
→ row state; constraint violations → real DB errors.
|
|
68
|
+
- **Event-driven (FastStream)**: publish to a real topic, consume, verify payload;
|
|
69
|
+
produce an event, verify processing + side effects.
|
|
70
|
+
- **Worker**: submit a real job → completion state; slow job → timeout + cleanup.
|
|
71
|
+
- **Agent (LLM)**: deterministic scripted LLM via real API → verify tool calls;
|
|
72
|
+
real tool execution → file/process state; real SSE/WS → event sequence.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Deriving Functional Requirements from a User Story
|
|
2
|
+
|
|
3
|
+
Load this when a request involves turning user stories into functional
|
|
4
|
+
requirements. It carries the *reasoning* for the derivation; the per-FR section
|
|
5
|
+
rules come from the `FR` template (`quoin write --types FR`).
|
|
6
|
+
|
|
7
|
+
## Rules
|
|
8
|
+
|
|
9
|
+
- **Atomic**: decompose the story into specific, single-behavior FRs.
|
|
10
|
+
- **Normative**: FRs use `SHALL` / `SHALL NOT` (a US never does).
|
|
11
|
+
- **No copying**: translate intent into a technical specification — do not paste
|
|
12
|
+
the story text.
|
|
13
|
+
- **Verifiable**: every FR carries its own Acceptance Criteria table.
|
|
14
|
+
|
|
15
|
+
## Process
|
|
16
|
+
|
|
17
|
+
1. **Analyze** the `US-XXX`: list the system responsibilities it implies.
|
|
18
|
+
2. **Decompose** into typed FRs. A behavioral FR (no `object:`) captures logic
|
|
19
|
+
and business rules. A domain-typed FR carries `object: <type>` and is purely
|
|
20
|
+
structural:
|
|
21
|
+
- `entity` — data model with typed fields
|
|
22
|
+
- `event` — a domain event emitted
|
|
23
|
+
- `api_endpoint` — a REST/HTTP endpoint
|
|
24
|
+
- `queue` — a message contract
|
|
25
|
+
- `process` — an end-to-end workflow
|
|
26
|
+
- `state_machine` — an entity lifecycle
|
|
27
|
+
- `configuration` — a configuration schema
|
|
28
|
+
- Full list + relationship verbs: `spec-object-review`'s
|
|
29
|
+
`references/object-type-guide.md`; inspect any type with
|
|
30
|
+
`quoin catalog show <type>`.
|
|
31
|
+
3. **Author** each FR as its own file (`quoin write --types FR` for the contract),
|
|
32
|
+
and link it back to the story via frontmatter `relationships:`
|
|
33
|
+
(`type: implements`, target the `US-XXX`).
|
|
34
|
+
4. **Specify** inputs/outputs (typed and validated), error handling (failure
|
|
35
|
+
modes), and constraints (technical limits, not options).
|
|
36
|
+
5. **Separation of concerns**: keep behavioral triggers/validation in behavioral
|
|
37
|
+
FRs; domain-typed FR acceptance criteria test **structure** only (schema/field
|
|
38
|
+
presence), never behavior. Do not duplicate behavioral ACs into a domain FR.
|
|
39
|
+
6. **Save** to `spec/functional/FR-XXX-description.md` (single repo) or
|
|
40
|
+
`specs/<category>/<component>/spec/functional/FR-XXX-description.md` (multi-repo).
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Writing Good Requirements
|
|
2
|
+
|
|
3
|
+
Load this when authoring StR/US/FR/NFR artifacts. The templates and Quire enforce
|
|
4
|
+
*shape*; this file carries the *judgment* that makes a requirement good, not just
|
|
5
|
+
well-formed. Authoring well here means `spec-review` has less to send back.
|
|
6
|
+
|
|
7
|
+
## Scope: tight beats broad
|
|
8
|
+
|
|
9
|
+
A narrow spec that fully defines its slice beats a sprawling one full of gaps.
|
|
10
|
+
Resist widening scope to "cover everything" — an expansive, vague spec is worse than
|
|
11
|
+
a tight, sharp one.
|
|
12
|
+
|
|
13
|
+
Treat the `spec.md` §2.2 **Out of Scope** list as first-class. Deliberately decide
|
|
14
|
+
what you are **not** building and write it down — an empty Out-of-Scope section is a
|
|
15
|
+
smell, not a default. Naming non-goals is how you prevent scope creep during
|
|
16
|
+
implementation.
|
|
17
|
+
|
|
18
|
+
> **Bad:** §2.2 left empty; §2.1 In Scope reads "all user-facing features".
|
|
19
|
+
> **Good:** In Scope: "CSV import of contacts". Out of Scope: "XLSX/JSON import,
|
|
20
|
+
> de-duplication, field mapping UI — see future work."
|
|
21
|
+
|
|
22
|
+
## User stories: INVEST + anti-patterns
|
|
23
|
+
|
|
24
|
+
Aim for **INVEST** stories: **I**ndependent, **N**egotiable, **V**aluable,
|
|
25
|
+
**E**stimable, **S**mall, **T**estable.
|
|
26
|
+
|
|
27
|
+
Catch these anti-patterns while authoring, not in review:
|
|
28
|
+
|
|
29
|
+
- **Vagueness** — "make it faster" says nothing testable. Name the user, the want,
|
|
30
|
+
and a measurable outcome.
|
|
31
|
+
- **Solution-prescribing** — "add a dropdown menu" prescribes a mechanism. A user
|
|
32
|
+
story describes the *need*; the FRs choose the mechanism. If the US already names
|
|
33
|
+
the implementation, you have skipped the problem.
|
|
34
|
+
- **Missing rationale** — every US carries a real "so that …". If you can't state the
|
|
35
|
+
value, question whether the story belongs in the spec.
|
|
36
|
+
- **Internal focus** — "so that the team has less to maintain" benefits the team, not
|
|
37
|
+
the user. Frame the value around the user/stakeholder outcome.
|
|
38
|
+
|
|
39
|
+
> **Bad:** "As a user, I want a dropdown to pick a timezone."
|
|
40
|
+
> **Good:** "As a traveling user, I want event times shown in my current timezone so
|
|
41
|
+
> that I don't miss meetings after I change locations." (The picker, if any, is an FR.)
|
|
42
|
+
|
|
43
|
+
## Acceptance criteria: cover the unhappy paths, be concrete
|
|
44
|
+
|
|
45
|
+
ACs are authored *here*, with the US/FR — don't defer coverage thinking to
|
|
46
|
+
`spec-matrix`. Front-load it:
|
|
47
|
+
|
|
48
|
+
- **Happy / error / edge from the start.** Walk the same ground the Six Coverage Rules
|
|
49
|
+
(`spec-matrix`) will later check — error paths, constraint boundaries, state
|
|
50
|
+
transitions, edge cases — while the behavior is fresh.
|
|
51
|
+
- **Negative cases.** State what must *not* happen, not just what should: rejects,
|
|
52
|
+
refuses, never persists, leaves state unchanged.
|
|
53
|
+
- **Concrete and measurable.** "Returns HTTP 422 within 200ms", not "handles errors
|
|
54
|
+
gracefully". Avoid subjective language (fast, robust, user-friendly) — if it can't
|
|
55
|
+
be measured, it can't be verified.
|
|
56
|
+
- **Behavior, not implementation.** Assert the observable outcome, not how the code
|
|
57
|
+
achieves it.
|
|
58
|
+
|
|
59
|
+
> **Bad:** "The system handles invalid input gracefully."
|
|
60
|
+
> **Good:** "Given a payload missing `email`, when POST /contacts is called, then the
|
|
61
|
+
> system returns HTTP 422 with error code `MISSING_FIELD` and persists no record."
|