@agent-ix/spec-artifacts-app 0.5.0 → 0.6.0

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 (48) hide show
  1. package/README.md +40 -1
  2. package/manifest.yaml +276 -4
  3. package/mappings.schema.json +318 -0
  4. package/mappings.yaml +386 -0
  5. package/package.json +10 -2
  6. package/schemas/Actor.json +34 -0
  7. package/schemas/ActorId.json +7 -0
  8. package/schemas/ActorKind.json +13 -0
  9. package/schemas/ApplicationSpec.json +116 -0
  10. package/schemas/ArtifactId.json +7 -0
  11. package/schemas/ArtifactStatus.json +7 -0
  12. package/schemas/Boundary.json +34 -0
  13. package/schemas/BoundaryId.json +7 -0
  14. package/schemas/BoundaryKind.json +12 -0
  15. package/schemas/Capability.json +37 -0
  16. package/schemas/CapabilityId.json +7 -0
  17. package/schemas/Cardinality.json +7 -0
  18. package/schemas/DataAccessMode.json +11 -0
  19. package/schemas/DataDependency.json +33 -0
  20. package/schemas/DataDependencyId.json +7 -0
  21. package/schemas/EdgeVerb.json +7 -0
  22. package/schemas/ImportedTypeRef.json +21 -0
  23. package/schemas/Interface.json +38 -0
  24. package/schemas/InterfaceDirection.json +11 -0
  25. package/schemas/InterfaceId.json +7 -0
  26. package/schemas/InterfaceKind.json +15 -0
  27. package/schemas/IxTarget.json +7 -0
  28. package/schemas/LineNumber.json +8 -0
  29. package/schemas/MasterRequirements.json +80 -0
  30. package/schemas/ModuleRef.json +7 -0
  31. package/schemas/NonEmptyText.json +7 -0
  32. package/schemas/Provenance.json +25 -0
  33. package/schemas/Relationship.json +24 -0
  34. package/schemas/RenderingRequirement.json +34 -0
  35. package/schemas/RenderingRequirementId.json +7 -0
  36. package/schemas/RequirementKind.json +14 -0
  37. package/schemas/RequirementRef.json +33 -0
  38. package/schemas/RequirementRefId.json +7 -0
  39. package/schemas/Section.json +26 -0
  40. package/schemas/Sha256Digest.json +7 -0
  41. package/schemas/TestCaseRef.json +7 -0
  42. package/schemas/TypeName.json +7 -0
  43. package/schemas/UiSurface.json +7 -0
  44. package/schemas/Verification.json +29 -0
  45. package/schemas/toolchain.json +65 -0
  46. package/skeletons/application-spec.md +163 -0
  47. package/skeletons/application-spec.sysml.md +167 -0
  48. package/skeletons/master-requirements.md +104 -0
@@ -0,0 +1,65 @@
1
+ {
2
+ "compiler": {
3
+ "name": "@typespec/compiler",
4
+ "version": "1.15.0"
5
+ },
6
+ "emitter": {
7
+ "name": "@typespec/json-schema",
8
+ "version": "1.15.0"
9
+ },
10
+ "semanticCore": {
11
+ "name": "@agent-ix/semantic-core",
12
+ "version": "0.3.0"
13
+ },
14
+ "base": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/0.2.0/",
15
+ "normalization": {
16
+ "name": "absolute-id-and-ref",
17
+ "version": "1.0.0",
18
+ "issue": "https://github.com/agent-ix/spec-artifacts-app/issues/3",
19
+ "applied": false,
20
+ "rewrittenFiles": [],
21
+ "note": "no-op: the emitter left no relative $id or $ref"
22
+ },
23
+ "files": [
24
+ "Actor.json",
25
+ "ActorId.json",
26
+ "ActorKind.json",
27
+ "ApplicationSpec.json",
28
+ "ArtifactId.json",
29
+ "ArtifactStatus.json",
30
+ "Boundary.json",
31
+ "BoundaryId.json",
32
+ "BoundaryKind.json",
33
+ "Capability.json",
34
+ "CapabilityId.json",
35
+ "Cardinality.json",
36
+ "DataAccessMode.json",
37
+ "DataDependency.json",
38
+ "DataDependencyId.json",
39
+ "EdgeVerb.json",
40
+ "ImportedTypeRef.json",
41
+ "Interface.json",
42
+ "InterfaceDirection.json",
43
+ "InterfaceId.json",
44
+ "InterfaceKind.json",
45
+ "IxTarget.json",
46
+ "LineNumber.json",
47
+ "MasterRequirements.json",
48
+ "ModuleRef.json",
49
+ "NonEmptyText.json",
50
+ "Provenance.json",
51
+ "Relationship.json",
52
+ "RenderingRequirement.json",
53
+ "RenderingRequirementId.json",
54
+ "RequirementKind.json",
55
+ "RequirementRef.json",
56
+ "RequirementRefId.json",
57
+ "Section.json",
58
+ "Sha256Digest.json",
59
+ "TestCaseRef.json",
60
+ "TypeName.json",
61
+ "UiSurface.json",
62
+ "Verification.json"
63
+ ],
64
+ "digest": "sha256:06c5422ddf061a3031e0c464083f53e7a8b065abae74d068d9a0be2a74c0cd51"
65
+ }
@@ -0,0 +1,163 @@
1
+ ---
2
+ id: AS-001
3
+ title: "Orders Platform"
4
+ type: ApplicationSpec
5
+ status: DRAFT
6
+ relationships:
7
+ - target: "ix://agent-ix/orders-platform/StR-001"
8
+ type: "references"
9
+ cardinality: "1:N"
10
+ ---
11
+ <!-- ApplicationSpec authoring skeleton (spec-artifacts-app). Fill every section
12
+ with substantive content. Contract (manifest body_extraction asserts):
13
+ - Frontmatter MUST carry id (^[A-Z]{2,4}-[0-9]+$), title, type: ApplicationSpec.
14
+ - REQUIRED: the H1 title, and "## Purpose" (H2).
15
+ - OPTIONAL (H2): Scope, System Overview, Structure,
16
+ Requirements Architecture, References, Properties, Boundaries,
17
+ Capabilities, Actors, Interfaces, Data Dependencies,
18
+ UI Rendering Requirements, Requirements, Invariants.
19
+ - "## Properties" is the typed field form, header exactly
20
+ `Field | Type | Multiplicity | Constraints`. Its alternate form is a
21
+ single ```sysml``` fence under the same heading — see
22
+ application-spec.sysml.md. One artifact carries ONE form.
23
+ - Each domain table's header row and its ID column pattern are fixed by
24
+ the archetype; ids are scoped to this document's id (AS-001-CAP-1).
25
+ - "## Requirements" rows REFERENCE a requirement another module owns:
26
+ the Source cell is `<org>/<repo>#<Type>` and must name a module and a
27
+ type declared in the manifest's `semantic.imports`. The requirement's
28
+ own fields belong to that module and are never copied here.
29
+ - "## Invariants": one `### <clauseId>` per clause, each owning exactly
30
+ one ```ocl``` fence. The clause text is carried verbatim, never parsed. -->
31
+ # [AS-001] Orders Platform
32
+
33
+ ## Purpose
34
+
35
+ The Orders Platform accepts customer orders from the storefront and the partner
36
+ API, prices and reserves them against inventory, and hands accepted orders to
37
+ fulfilment. This document is the composite specification for the platform as a
38
+ whole: it names what the platform owns, who uses it, what it talks to, and which
39
+ per-service requirements it rolls up.
40
+
41
+ ## Scope
42
+
43
+ In scope: order intake, pricing, reservation, and the handoff to fulfilment.
44
+ Out of scope: payment capture, which the Payments Platform owns and this
45
+ platform only calls; and warehouse operations downstream of the handoff.
46
+
47
+ ## System Overview
48
+
49
+ Three services sit behind one HTTP gateway. `order-intake` validates and
50
+ persists submissions, `order-pricing` prices and reserves them, and
51
+ `order-handoff` publishes accepted orders to the fulfilment topic. The three
52
+ share one Postgres cluster and one event bus, and none is reachable from outside
53
+ the gateway.
54
+
55
+ ## Structure
56
+
57
+ - `services/order-intake/spec/` — intake requirements.
58
+ - `services/order-pricing/spec/` — pricing and reservation requirements.
59
+ - `services/order-handoff/spec/` — handoff requirements.
60
+ - `spec/tests.md` — the platform-level test matrix.
61
+
62
+ ## Requirements Architecture
63
+
64
+ Stakeholder needs live in `services/*/spec/stakeholder/`, are told as stories in
65
+ `usecase/`, and are made normative in `functional/` and `non-functional/`. This
66
+ document rolls them up; it introduces no requirement of its own.
67
+
68
+ ## References
69
+
70
+ - ISO/IEC/IEEE 29148 — Requirements engineering.
71
+ - The three service bundles named in Structure.
72
+
73
+ ## Properties
74
+
75
+ | Field | Type | Multiplicity | Constraints |
76
+ |---|---|---|---|
77
+ | application_id | UUID | 1..1 | identity |
78
+ | slug | String | 1..1 | pattern: /^[a-z][a-z0-9-]*$/ |
79
+ | display_name | String | 1..1 | minLength: 1, maxLength: 120 |
80
+ | owning_team | String | 1..1 | nonEmpty |
81
+ | launched_at | Timestamp | 0..1 | |
82
+
83
+ ## Boundaries
84
+
85
+ | ID | Name | Kind | Description |
86
+ |---|---|---|---|
87
+ | AS-001-BND-1 | Order lifecycle | owned | Intake, pricing, reservation, and handoff are specified and operated by this platform. |
88
+ | AS-001-BND-2 | Payment capture | consumed | Called synchronously at checkout; specified by the Payments Platform. |
89
+ | AS-001-BND-3 | Carrier rate lookup | external | A third-party rate service with its own availability contract. |
90
+ | AS-001-BND-4 | Returns | deferred | Named so its absence is deliberate; no requirement here covers it. |
91
+
92
+ ## Capabilities
93
+
94
+ | ID | Name | Description | Actors |
95
+ |---|---|---|---|
96
+ | AS-001-CAP-1 | Submit an order | Accept an order from the storefront or the partner API and persist it as submitted. | AS-001-ACT-1, AS-001-ACT-3 |
97
+ | AS-001-CAP-2 | Price and reserve | Price a submitted order and reserve its lines against inventory. | AS-001-ACT-2 |
98
+ | AS-001-CAP-3 | Hand off to fulfilment | Publish an accepted order to the fulfilment topic exactly once. | AS-001-ACT-4 |
99
+
100
+ ## Actors
101
+
102
+ | ID | Name | Kind | Description |
103
+ |---|---|---|---|
104
+ | AS-001-ACT-1 | Shopper | human | Places orders through the storefront. |
105
+ | AS-001-ACT-2 | Inventory service | service | Holds and releases reservations against stock. |
106
+ | AS-001-ACT-3 | Partner integration | external_system | Submits orders on a partner's behalf over the partner API. |
107
+ | AS-001-ACT-4 | Nightly reconciler | scheduler | Re-drives orders stuck between reservation and handoff. |
108
+
109
+ ## Interfaces
110
+
111
+ | ID | Name | Kind | Direction | Contract |
112
+ |---|---|---|---|---|
113
+ | AS-001-IFC-1 | Storefront order API | http_api | inbound | POST /api/v1/orders |
114
+ | AS-001-IFC-2 | Inventory reservation API | http_api | outbound | POST /api/v1/reservations |
115
+ | AS-001-IFC-3 | Fulfilment topic | event_stream | outbound | orders.accepted.v1 |
116
+ | AS-001-IFC-4 | Operator console | ui | inbound | /console/orders |
117
+
118
+ ## Data Dependencies
119
+
120
+ | ID | Name | Source | Access |
121
+ |---|---|---|---|
122
+ | AS-001-DAT-1 | Stakeholder requirements rolled up | agent-ix/spec-artifacts-iso#StR | read |
123
+ | AS-001-DAT-2 | Functional requirements rolled up | agent-ix/spec-artifacts-iso#FR | read |
124
+ | AS-001-DAT-3 | Integration tests rolled up | agent-ix/spec-artifacts-iso#IT | read |
125
+
126
+ ## UI Rendering Requirements
127
+
128
+ | ID | Surface | Requirement | Verification |
129
+ |---|---|---|---|
130
+ | AS-001-UI-1 | web | The order detail view shall render every line item with its reserved quantity. | Test (TC-101) |
131
+ | AS-001-UI-2 | web | The order list shall render a reservation-failed order with its failure reason visible without opening the order. | Test (TC-102) |
132
+ | AS-001-UI-3 | cli | `orders show <id>` shall print the same lifecycle state the web view renders. | Demonstration |
133
+
134
+ ## Requirements
135
+
136
+ | ID | Kind | Source | Target |
137
+ |---|---|---|---|
138
+ | StR-001 | StR | agent-ix/spec-artifacts-iso#StR | ix://agent-ix/orders-platform/StR-001 |
139
+ | FR-014 | FR | agent-ix/spec-artifacts-iso#FR | ix://agent-ix/orders-platform/FR-014 |
140
+ | NFR-003 | NFR | agent-ix/spec-artifacts-iso#NFR | ix://agent-ix/orders-platform/NFR-003 |
141
+ | IT-002 | IT | agent-ix/spec-artifacts-iso#IT | ix://agent-ix/orders-platform/IT-002 |
142
+
143
+ ## Invariants
144
+
145
+ The clauses this application declaration enforces. Each clause owns one `ocl`
146
+ fence under its own `### <clauseId>` heading; the fence text is carried verbatim
147
+ and is never evaluated here.
148
+
149
+ ### EveryCapabilityNamesAnActor
150
+
151
+ ```ocl
152
+ context ApplicationSpec
153
+ inv EveryCapabilityNamesAnActor:
154
+ self.capabilities->forAll(c | c.actors->notEmpty())
155
+ ```
156
+
157
+ ### DeferredBoundaryCarriesNoInterface
158
+
159
+ ```ocl
160
+ context ApplicationSpec
161
+ inv DeferredBoundaryCarriesNoInterface:
162
+ self.boundaries->select(b | b.kind = BoundaryKind::deferred)->forAll(b | self.interfaces->isEmpty() or true)
163
+ ```
@@ -0,0 +1,167 @@
1
+ ---
2
+ id: AS-001
3
+ title: "Orders Platform"
4
+ type: ApplicationSpec
5
+ status: DRAFT
6
+ relationships:
7
+ - target: "ix://agent-ix/orders-platform/StR-001"
8
+ type: "references"
9
+ cardinality: "1:N"
10
+ ---
11
+ <!-- ApplicationSpec authoring skeleton, ALTERNATE Properties form. Declares
12
+ exactly the same fields as application-spec.md, in the same order,
13
+ authored as one `sysml` fence instead of the typed table (FR-005-AC-2).
14
+ One artifact carries one form; the alternate is a separate file, never a
15
+ second block in the same artifact. Every other section is identical.
16
+ Fill every section with substantive content. Contract (manifest body_extraction asserts):
17
+ - Frontmatter MUST carry id (^[A-Z]{2,4}-[0-9]+$), title, type: ApplicationSpec.
18
+ - REQUIRED: the H1 title, and "## Purpose" (H2).
19
+ - OPTIONAL (H2): Scope, System Overview, Structure,
20
+ Requirements Architecture, References, Properties, Boundaries,
21
+ Capabilities, Actors, Interfaces, Data Dependencies,
22
+ UI Rendering Requirements, Requirements, Invariants.
23
+ - "## Properties" here is the single ```sysml``` fence form. Its
24
+ counterpart is the typed table, header exactly
25
+ `Field | Type | Multiplicity | Constraints` — see application-spec.md.
26
+ One artifact carries ONE form.
27
+ - Each domain table's header row and its ID column pattern are fixed by
28
+ the archetype; ids are scoped to this document's id (AS-001-CAP-1).
29
+ - "## Requirements" rows REFERENCE a requirement another module owns:
30
+ the Source cell is `<org>/<repo>#<Type>` and must name a module and a
31
+ type declared in the manifest's `semantic.imports`. The requirement's
32
+ own fields belong to that module and are never copied here.
33
+ - "## Invariants": one `### <clauseId>` per clause, each owning exactly
34
+ one ```ocl``` fence. The clause text is carried verbatim, never parsed. -->
35
+ # [AS-001] Orders Platform
36
+
37
+ ## Purpose
38
+
39
+ The Orders Platform accepts customer orders from the storefront and the partner
40
+ API, prices and reserves them against inventory, and hands accepted orders to
41
+ fulfilment. This document is the composite specification for the platform as a
42
+ whole: it names what the platform owns, who uses it, what it talks to, and which
43
+ per-service requirements it rolls up.
44
+
45
+ ## Scope
46
+
47
+ In scope: order intake, pricing, reservation, and the handoff to fulfilment.
48
+ Out of scope: payment capture, which the Payments Platform owns and this
49
+ platform only calls; and warehouse operations downstream of the handoff.
50
+
51
+ ## System Overview
52
+
53
+ Three services sit behind one HTTP gateway. `order-intake` validates and
54
+ persists submissions, `order-pricing` prices and reserves them, and
55
+ `order-handoff` publishes accepted orders to the fulfilment topic. The three
56
+ share one Postgres cluster and one event bus, and none is reachable from outside
57
+ the gateway.
58
+
59
+ ## Structure
60
+
61
+ - `services/order-intake/spec/` — intake requirements.
62
+ - `services/order-pricing/spec/` — pricing and reservation requirements.
63
+ - `services/order-handoff/spec/` — handoff requirements.
64
+ - `spec/tests.md` — the platform-level test matrix.
65
+
66
+ ## Requirements Architecture
67
+
68
+ Stakeholder needs live in `services/*/spec/stakeholder/`, are told as stories in
69
+ `usecase/`, and are made normative in `functional/` and `non-functional/`. This
70
+ document rolls them up; it introduces no requirement of its own.
71
+
72
+ ## References
73
+
74
+ - ISO/IEC/IEEE 29148 — Requirements engineering.
75
+ - The three service bundles named in Structure.
76
+
77
+ ## Properties
78
+
79
+ ```sysml
80
+ attribute application_id : UUID[1..1] { identity }
81
+ attribute slug : String[1..1] { pattern: /^[a-z][a-z0-9-]*$/ }
82
+ attribute display_name : String[1..1] { minLength: 1, maxLength: 120 }
83
+ attribute owning_team : String[1..1] { nonEmpty }
84
+ attribute launched_at : Timestamp[0..1]
85
+ ```
86
+
87
+ ## Boundaries
88
+
89
+ | ID | Name | Kind | Description |
90
+ |---|---|---|---|
91
+ | AS-001-BND-1 | Order lifecycle | owned | Intake, pricing, reservation, and handoff are specified and operated by this platform. |
92
+ | AS-001-BND-2 | Payment capture | consumed | Called synchronously at checkout; specified by the Payments Platform. |
93
+ | AS-001-BND-3 | Carrier rate lookup | external | A third-party rate service with its own availability contract. |
94
+ | AS-001-BND-4 | Returns | deferred | Named so its absence is deliberate; no requirement here covers it. |
95
+
96
+ ## Capabilities
97
+
98
+ | ID | Name | Description | Actors |
99
+ |---|---|---|---|
100
+ | AS-001-CAP-1 | Submit an order | Accept an order from the storefront or the partner API and persist it as submitted. | AS-001-ACT-1, AS-001-ACT-3 |
101
+ | AS-001-CAP-2 | Price and reserve | Price a submitted order and reserve its lines against inventory. | AS-001-ACT-2 |
102
+ | AS-001-CAP-3 | Hand off to fulfilment | Publish an accepted order to the fulfilment topic exactly once. | AS-001-ACT-4 |
103
+
104
+ ## Actors
105
+
106
+ | ID | Name | Kind | Description |
107
+ |---|---|---|---|
108
+ | AS-001-ACT-1 | Shopper | human | Places orders through the storefront. |
109
+ | AS-001-ACT-2 | Inventory service | service | Holds and releases reservations against stock. |
110
+ | AS-001-ACT-3 | Partner integration | external_system | Submits orders on a partner's behalf over the partner API. |
111
+ | AS-001-ACT-4 | Nightly reconciler | scheduler | Re-drives orders stuck between reservation and handoff. |
112
+
113
+ ## Interfaces
114
+
115
+ | ID | Name | Kind | Direction | Contract |
116
+ |---|---|---|---|---|
117
+ | AS-001-IFC-1 | Storefront order API | http_api | inbound | POST /api/v1/orders |
118
+ | AS-001-IFC-2 | Inventory reservation API | http_api | outbound | POST /api/v1/reservations |
119
+ | AS-001-IFC-3 | Fulfilment topic | event_stream | outbound | orders.accepted.v1 |
120
+ | AS-001-IFC-4 | Operator console | ui | inbound | /console/orders |
121
+
122
+ ## Data Dependencies
123
+
124
+ | ID | Name | Source | Access |
125
+ |---|---|---|---|
126
+ | AS-001-DAT-1 | Stakeholder requirements rolled up | agent-ix/spec-artifacts-iso#StR | read |
127
+ | AS-001-DAT-2 | Functional requirements rolled up | agent-ix/spec-artifacts-iso#FR | read |
128
+ | AS-001-DAT-3 | Integration tests rolled up | agent-ix/spec-artifacts-iso#IT | read |
129
+
130
+ ## UI Rendering Requirements
131
+
132
+ | ID | Surface | Requirement | Verification |
133
+ |---|---|---|---|
134
+ | AS-001-UI-1 | web | The order detail view shall render every line item with its reserved quantity. | Test (TC-101) |
135
+ | AS-001-UI-2 | web | The order list shall render a reservation-failed order with its failure reason visible without opening the order. | Test (TC-102) |
136
+ | AS-001-UI-3 | cli | `orders show <id>` shall print the same lifecycle state the web view renders. | Demonstration |
137
+
138
+ ## Requirements
139
+
140
+ | ID | Kind | Source | Target |
141
+ |---|---|---|---|
142
+ | StR-001 | StR | agent-ix/spec-artifacts-iso#StR | ix://agent-ix/orders-platform/StR-001 |
143
+ | FR-014 | FR | agent-ix/spec-artifacts-iso#FR | ix://agent-ix/orders-platform/FR-014 |
144
+ | NFR-003 | NFR | agent-ix/spec-artifacts-iso#NFR | ix://agent-ix/orders-platform/NFR-003 |
145
+ | IT-002 | IT | agent-ix/spec-artifacts-iso#IT | ix://agent-ix/orders-platform/IT-002 |
146
+
147
+ ## Invariants
148
+
149
+ The clauses this application declaration enforces. Each clause owns one `ocl`
150
+ fence under its own `### <clauseId>` heading; the fence text is carried verbatim
151
+ and is never evaluated here.
152
+
153
+ ### EveryCapabilityNamesAnActor
154
+
155
+ ```ocl
156
+ context ApplicationSpec
157
+ inv EveryCapabilityNamesAnActor:
158
+ self.capabilities->forAll(c | c.actors->notEmpty())
159
+ ```
160
+
161
+ ### DeferredBoundaryCarriesNoInterface
162
+
163
+ ```ocl
164
+ context ApplicationSpec
165
+ inv DeferredBoundaryCarriesNoInterface:
166
+ self.boundaries->select(b | b.kind = BoundaryKind::deferred)->forAll(b | self.interfaces->isEmpty() or true)
167
+ ```
@@ -0,0 +1,104 @@
1
+ ---
2
+ id: MR-001
3
+ title: "Orders Platform master requirements"
4
+ type: MasterRequirements
5
+ status: DRAFT
6
+ relationships:
7
+ - target: "ix://agent-ix/orders-platform/AS-001"
8
+ type: "aggregates"
9
+ cardinality: "1:1"
10
+ ---
11
+ <!-- MasterRequirements authoring skeleton (spec-artifacts-app). Fill every
12
+ section with substantive content. Contract (manifest body_extraction
13
+ asserts):
14
+ - Frontmatter MUST carry id (^[A-Z]{2,4}-[0-9]+$), title,
15
+ type: MasterRequirements.
16
+ - REQUIRED: the H1 title, and "## Purpose" (H2).
17
+ - OPTIONAL (H2): Scope, System Overview, Structure,
18
+ Requirements Architecture, References, Properties, Requirements,
19
+ Invariants.
20
+ - A MasterRequirements document is the front page of a specification, not
21
+ a description of a running system: it declares no Boundaries,
22
+ Capabilities, Actors, Interfaces, Data Dependencies, or UI Rendering
23
+ Requirements. Those belong to ApplicationSpec.
24
+ - "## Properties" is the typed field form, header exactly
25
+ `Field | Type | Multiplicity | Constraints`; its alternate form is a
26
+ single ```sysml``` fence under the same heading. One artifact carries
27
+ ONE form.
28
+ - "## Requirements" rows REFERENCE a requirement another module owns: the
29
+ Source cell is `<org>/<repo>#<Type>` and must name a module and a type
30
+ declared in the manifest's `semantic.imports`. The requirement's own
31
+ fields belong to that module and are never copied here.
32
+ - "## Invariants": one `### <clauseId>` per clause, each owning exactly
33
+ one ```ocl``` fence; the text is carried verbatim, never parsed. -->
34
+ # [MR-001] Orders Platform master requirements
35
+
36
+ ## Purpose
37
+
38
+ This document is the front page of the Orders Platform specification. It states
39
+ what the specification is for, which requirement sets it rolls up, and where the
40
+ authoritative text for each of them lives. It restates none of those
41
+ requirements: each row of `## Requirements` references the module that owns the
42
+ requirement's type.
43
+
44
+ ## Scope
45
+
46
+ Covers the three order services and the contracts between them. Excludes the
47
+ Payments Platform and warehouse operations, which carry their own master
48
+ requirements documents.
49
+
50
+ ## System Overview
51
+
52
+ The specification is organised per service, with this document as the roll-up.
53
+ Every requirement referenced here is authored once, in the service bundle that
54
+ owns it, and is read from there.
55
+
56
+ ## Structure
57
+
58
+ - `services/*/spec/stakeholder/` — StR artifacts.
59
+ - `services/*/spec/functional/` — FR artifacts.
60
+ - `services/*/spec/non-functional/` — NFR artifacts.
61
+ - `services/*/spec/integration/` — IT artifacts.
62
+
63
+ ## Requirements Architecture
64
+
65
+ Stakeholder needs live in `services/*/spec/stakeholder/`, are told as stories in
66
+ `usecase/`, and are made normative in `functional/` and `non-functional/`. This
67
+ document rolls them up; it introduces no requirement of its own.
68
+
69
+ ## References
70
+
71
+ - ISO/IEC/IEEE 29148 — Requirements engineering.
72
+ - The three service bundles named in Structure.
73
+
74
+ ## Properties
75
+
76
+ | Field | Type | Multiplicity | Constraints |
77
+ |---|---|---|---|
78
+ | specification_id | UUID | 1..1 | identity |
79
+ | slug | String | 1..1 | pattern: /^[a-z][a-z0-9-]*$/ |
80
+ | revision | Integer | 1..1 | min: 1 |
81
+ | approved_at | Timestamp | 0..1 | |
82
+
83
+ ## Requirements
84
+
85
+ | ID | Kind | Source | Target |
86
+ |---|---|---|---|
87
+ | StR-001 | StR | agent-ix/spec-artifacts-iso#StR | ix://agent-ix/orders-platform/StR-001 |
88
+ | US-004 | US | agent-ix/spec-artifacts-iso#US | ix://agent-ix/orders-platform/US-004 |
89
+ | FR-014 | FR | agent-ix/spec-artifacts-iso#FR | ix://agent-ix/orders-platform/FR-014 |
90
+ | TC-021 | TC | agent-ix/spec-artifacts-iso#TC | ix://agent-ix/orders-platform/TC-021 |
91
+
92
+ ## Invariants
93
+
94
+ The clauses this specification declaration enforces. Each clause owns one `ocl`
95
+ fence under its own `### <clauseId>` heading; the fence text is carried verbatim
96
+ and is never evaluated here.
97
+
98
+ ### EveryReferencedRequirementNamesAnImportedType
99
+
100
+ ```ocl
101
+ context MasterRequirements
102
+ inv EveryReferencedRequirementNamesAnImportedType:
103
+ self.requirements->forAll(r | r.source.module->notEmpty() and r.source.type->notEmpty())
104
+ ```