@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.
Files changed (215) hide show
  1. package/.agents/plugins/marketplace.json +14 -0
  2. package/.claude-plugin/marketplace.json +16 -0
  3. package/.claude-plugin/plugin.json +8 -0
  4. package/.codex-plugin/plugin.json +27 -0
  5. package/.github/plugin/marketplace.json +16 -0
  6. package/LICENSE +21 -0
  7. package/README.md +266 -0
  8. package/bin/quoin.js +14 -0
  9. package/default-modules.yaml +82 -0
  10. package/dist/base-DrUMkAh1.js +137 -0
  11. package/dist/base.d.ts +23 -0
  12. package/dist/base.d.ts.map +1 -0
  13. package/dist/catalog.d.ts +32 -0
  14. package/dist/catalog.d.ts.map +1 -0
  15. package/dist/cli.d.ts +18 -0
  16. package/dist/cli.d.ts.map +1 -0
  17. package/dist/cli.js +20 -0
  18. package/dist/commands/catalog/index.d.ts +2 -0
  19. package/dist/commands/catalog/index.d.ts.map +1 -0
  20. package/dist/commands/catalog/index.js +2 -0
  21. package/dist/commands/catalog/list.d.ts +11 -0
  22. package/dist/commands/catalog/list.d.ts.map +1 -0
  23. package/dist/commands/catalog/list.js +22 -0
  24. package/dist/commands/catalog/show.d.ts +13 -0
  25. package/dist/commands/catalog/show.d.ts.map +1 -0
  26. package/dist/commands/catalog/show.js +25 -0
  27. package/dist/commands/catalog/validate.d.ts +10 -0
  28. package/dist/commands/catalog/validate.d.ts.map +1 -0
  29. package/dist/commands/catalog/validate.js +27 -0
  30. package/dist/commands/config/doctor.d.ts +7 -0
  31. package/dist/commands/config/doctor.d.ts.map +1 -0
  32. package/dist/commands/config/doctor.js +15 -0
  33. package/dist/commands/config/edit.d.ts +7 -0
  34. package/dist/commands/config/edit.d.ts.map +1 -0
  35. package/dist/commands/config/edit.js +13 -0
  36. package/dist/commands/config/get.d.ts +11 -0
  37. package/dist/commands/config/get.d.ts.map +1 -0
  38. package/dist/commands/config/get.js +20 -0
  39. package/dist/commands/config/index.d.ts +2 -0
  40. package/dist/commands/config/index.d.ts.map +1 -0
  41. package/dist/commands/config/index.js +2 -0
  42. package/dist/commands/config/set.d.ts +12 -0
  43. package/dist/commands/config/set.d.ts.map +1 -0
  44. package/dist/commands/config/set.js +26 -0
  45. package/dist/commands/matrix.d.ts +14 -0
  46. package/dist/commands/matrix.d.ts.map +1 -0
  47. package/dist/commands/matrix.js +15 -0
  48. package/dist/commands/module/ensure-defaults.d.ts +8 -0
  49. package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
  50. package/dist/commands/module/ensure-defaults.js +17 -0
  51. package/dist/commands/module/index.d.ts +2 -0
  52. package/dist/commands/module/index.d.ts.map +1 -0
  53. package/dist/commands/module/index.js +2 -0
  54. package/dist/commands/module/install.d.ts +11 -0
  55. package/dist/commands/module/install.d.ts.map +1 -0
  56. package/dist/commands/module/install.js +22 -0
  57. package/dist/commands/module/list.d.ts +8 -0
  58. package/dist/commands/module/list.d.ts.map +1 -0
  59. package/dist/commands/module/list.js +13 -0
  60. package/dist/commands/module/remove.d.ts +10 -0
  61. package/dist/commands/module/remove.d.ts.map +1 -0
  62. package/dist/commands/module/remove.js +16 -0
  63. package/dist/commands/plugin/deprecation.d.ts +10 -0
  64. package/dist/commands/plugin/deprecation.d.ts.map +1 -0
  65. package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
  66. package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
  67. package/dist/commands/plugin/ensure-defaults.js +12 -0
  68. package/dist/commands/plugin/index.d.ts +2 -0
  69. package/dist/commands/plugin/index.d.ts.map +1 -0
  70. package/dist/commands/plugin/index.js +2 -0
  71. package/dist/commands/plugin/install.d.ts +8 -0
  72. package/dist/commands/plugin/install.d.ts.map +1 -0
  73. package/dist/commands/plugin/install.js +12 -0
  74. package/dist/commands/plugin/list.d.ts +8 -0
  75. package/dist/commands/plugin/list.d.ts.map +1 -0
  76. package/dist/commands/plugin/list.js +12 -0
  77. package/dist/commands/plugin/remove.d.ts +8 -0
  78. package/dist/commands/plugin/remove.d.ts.map +1 -0
  79. package/dist/commands/plugin/remove.js +12 -0
  80. package/dist/commands/review.d.ts +14 -0
  81. package/dist/commands/review.d.ts.map +1 -0
  82. package/dist/commands/review.js +15 -0
  83. package/dist/commands/to-plan.d.ts +14 -0
  84. package/dist/commands/to-plan.d.ts.map +1 -0
  85. package/dist/commands/to-plan.js +15 -0
  86. package/dist/commands/update.d.ts +13 -0
  87. package/dist/commands/update.d.ts.map +1 -0
  88. package/dist/commands/update.js +34 -0
  89. package/dist/commands/write.d.ts +16 -0
  90. package/dist/commands/write.d.ts.map +1 -0
  91. package/dist/commands/write.js +33 -0
  92. package/dist/config-schema-Dp-vlxuR.js +13 -0
  93. package/dist/config-schema.d.ts +52 -0
  94. package/dist/config-schema.d.ts.map +1 -0
  95. package/dist/deprecation-fRxUHoxv.js +4 -0
  96. package/dist/flow-command-SMjCSOFg.js +88 -0
  97. package/dist/flow-command.d.ts +25 -0
  98. package/dist/flow-command.d.ts.map +1 -0
  99. package/dist/flows.d.ts +7 -0
  100. package/dist/flows.d.ts.map +1 -0
  101. package/dist/index.d.ts +11 -0
  102. package/dist/index.d.ts.map +1 -0
  103. package/dist/index.js +9 -0
  104. package/dist/modules-CW8pBK41.js +22 -0
  105. package/dist/modules.d.ts +10 -0
  106. package/dist/modules.d.ts.map +1 -0
  107. package/dist/org.d.ts +61 -0
  108. package/dist/org.d.ts.map +1 -0
  109. package/dist/plugins-GSxafyD3.js +77 -0
  110. package/dist/plugins.d.ts +13 -0
  111. package/dist/plugins.d.ts.map +1 -0
  112. package/dist/version-_1nY4KyJ.js +17 -0
  113. package/dist/version.d.ts +3 -0
  114. package/dist/version.d.ts.map +1 -0
  115. package/dist/write-CQAitcI5.js +156 -0
  116. package/dist/write.d.ts +28 -0
  117. package/dist/write.d.ts.map +1 -0
  118. package/package.json +119 -0
  119. package/skills/gap-analysis/SKILL.md +97 -0
  120. package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
  121. package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
  122. package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
  123. package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
  124. package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
  125. package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
  126. package/skills/spec-app-review/SKILL.md +51 -0
  127. package/skills/spec-app-review/references/checklist.md +197 -0
  128. package/skills/spec-dependency-analysis/SKILL.md +75 -0
  129. package/skills/spec-ears-analysis/SKILL.md +89 -0
  130. package/skills/spec-evidence-analysis/SKILL.md +78 -0
  131. package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
  132. package/skills/spec-ideation/SKILL.md +46 -0
  133. package/skills/spec-integrity-analysis/SKILL.md +47 -0
  134. package/skills/spec-matrix/SKILL.md +168 -0
  135. package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
  136. package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
  137. package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
  138. package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
  139. package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
  140. package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
  141. package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
  142. package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
  143. package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
  144. package/skills/spec-object-review/SKILL.md +125 -0
  145. package/skills/spec-object-review/references/object-type-guide.md +118 -0
  146. package/skills/spec-review/SKILL.md +71 -0
  147. package/skills/spec-review/references/checklist.md +50 -0
  148. package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
  149. package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
  150. package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
  151. package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
  152. package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
  153. package/skills/spec-security-analysis/SKILL.md +84 -0
  154. package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
  155. package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
  156. package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
  157. package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
  158. package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
  159. package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
  160. package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
  161. package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
  162. package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
  163. package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
  164. package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
  165. package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
  166. package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
  167. package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
  168. package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
  169. package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
  170. package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
  171. package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
  172. package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
  173. package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
  174. package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
  175. package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
  176. package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
  177. package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
  178. package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
  179. package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
  180. package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
  181. package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
  182. package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
  183. package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
  184. package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
  185. package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
  186. package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
  187. package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
  188. package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
  189. package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
  190. package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
  191. package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
  192. package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
  193. package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
  194. package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
  195. package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
  196. package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
  197. package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
  198. package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
  199. package/skills/spec-security-analysis/references/soc2/index.md +46 -0
  200. package/skills/spec-security-analysis/references/standards-index.md +46 -0
  201. package/skills/spec-to-plan/SKILL.md +75 -0
  202. package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
  203. package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
  204. package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
  205. package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
  206. package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
  207. package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
  208. package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
  209. package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
  210. package/skills/specify/SKILL.md +154 -0
  211. package/skills/specify/assets/app-spec-template.md +143 -0
  212. package/skills/specify/assets/spec-template.md +299 -0
  213. package/skills/specify/references/integration-tests.md +72 -0
  214. package/skills/specify/references/us-to-fr.md +40 -0
  215. 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."