@agent-ix/spec-artifacts-app 0.9.0 → 0.10.1

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/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/k8DVhuYBR2)
4
4
 
5
- > Filament Module: application/composite spec artifact templates (ApplicationSpec, MasterRequirements) — absorbed spec-master-requirements
5
+ > Filament Module: application/composite spec artifact templates (ApplicationSpec); `master-requirements` is imported from `spec-artifacts-iso`
6
6
 
7
7
  Agent-IX Filament module loaded by [`quire-cli`](https://github.com/agent-ix/quire-cli) and [`quoin`](https://github.com/agent-ix/quoin).
8
8
 
@@ -60,7 +60,6 @@ This module gives you the top-level document kinds for specifying a whole applic
60
60
  | Kind | Type | What it's for |
61
61
  |:-----|:-----|:--------------|
62
62
  | `ApplicationSpec` | Application Spec | The top-level document for an application — describes the system as a whole and gathers together the requirements and specs that make it up. |
63
- | `MasterRequirements` | Master Requirements | The front page of a specification — its purpose, scope, and the set of requirements it rolls up. |
64
63
 
65
64
  ## How this module is used
66
65
 
package/manifest.yaml CHANGED
@@ -1,25 +1,33 @@
1
1
  manifest_version: 1.0.0
2
2
  name: spec-artifacts-app
3
3
  version: 0.2.0
4
- description: "Filament Module: application/composite spec artifact templates (ApplicationSpec, MasterRequirements) — absorbed spec-master-requirements"
4
+ description: "Filament Module: application/composite spec artifact templates (ApplicationSpec); master-requirements is imported from spec-artifacts-iso"
5
5
  # Semantic-module contract (quoin FR-070/FR-073, agent-ix/spec-artifacts-app#3).
6
6
  # `imports` names every module whose types this module's artifacts reference;
7
7
  # an artifact references an imported type through `{module, type}` and an id,
8
8
  # never by restating the imported type's fields (FR-002-AC-10, FR-003-AC-4).
9
+ # The engine counts an import as used only when a `$ref` in the module's own
10
+ # data schemas names a type under that package's schema base (`RequirementRef.$defs`).
9
11
  semantic:
10
12
  contract_version: 1.0.0
11
- semantic_core: 0.3.2
12
13
  package: agent-ix/spec-artifacts-app
13
14
  exports:
14
15
  - ApplicationSpec
15
- - MasterRequirements
16
- # FR-035 types `imports` as `<org>/<repo>` -> exact semver, and nothing more.
17
- # The *types* this module references from each imported package are declared
18
- # in `mappings.yaml` under `imported_types`, because the contract has no place
19
- # for them yet (agent-ix/quoin#339). The suite checks every `ImportedTypeRef`
20
- # against both: the package here, the type there.
16
+ # `imports` is `<org>/<repo>` -> exact semver; `import_types` lists the types
17
+ # this module references from each imported package. The suite checks every
18
+ # `ImportedTypeRef` against both, and the engine refuses a listed type the
19
+ # provider does not export.
21
20
  imports:
22
21
  agent-ix/spec-artifacts-iso: 0.3.0
22
+ import_types:
23
+ agent-ix/spec-artifacts-iso:
24
+ - StR
25
+ - US
26
+ - FR
27
+ - NFR
28
+ - IT
29
+ - TC
30
+ - master-requirements
23
31
  targets: [json-schema, markdown]
24
32
  mappings: [frontmatter, section, typed-table, sysml-fence, ocl-clause, provenance]
25
33
  compatibility_posture: additive
@@ -31,7 +39,7 @@ archetypes:
31
39
  supports_membership: true
32
40
  composition:
33
41
  expected_artifacts:
34
- - MasterRequirements
42
+ - master-requirements
35
43
  - StR
36
44
  - FR
37
45
  - NFR
@@ -41,7 +49,6 @@ grammars:
41
49
  description: Composite application spec grammar
42
50
  doc_kinds:
43
51
  - application-spec
44
- - master-requirements
45
52
  artifact_types:
46
53
  - name: ApplicationSpec
47
54
  grammar_ref: app-spec
@@ -219,102 +226,7 @@ artifact_types:
219
226
  under_section: Invariants
220
227
  required: false
221
228
  multiple: true
222
- - name: MasterRequirements
223
- grammar_ref: app-spec
224
- frontmatter_schema_ref: schemas/masterrequirements-frontmatter.schema.json
225
- data_schema:
226
- schema: schemas/MasterRequirements.json
227
- defaults:
228
- id_pattern: MR-{next:03d}
229
- allowed_links:
230
- - aggregates
231
- - depends_on
232
- - references
233
- examples: []
234
- lint_rules_ref: []
235
- body_extraction:
236
- yield_pattern:
237
- match:
238
- title:
239
- from: heading
240
- level: 1
241
- required: true
242
- assert:
243
- level: 1
244
- purpose:
245
- from: section_body
246
- after_heading: Purpose
247
- required: true
248
- assert:
249
- level: 2
250
- scope:
251
- from: section_body
252
- after_heading: Scope
253
- required: false
254
- assert:
255
- level: 2
256
- system_overview:
257
- from: section_body
258
- after_heading: System Overview
259
- required: false
260
- assert:
261
- level: 2
262
- structure:
263
- from: section_body
264
- after_heading: Structure
265
- required: false
266
- assert:
267
- level: 2
268
- requirements_architecture:
269
- from: section_body
270
- after_heading: Requirements Architecture
271
- required: false
272
- assert:
273
- level: 2
274
- references:
275
- from: section_body
276
- after_heading: References
277
- required: false
278
- assert:
279
- level: 2
280
- requirements_table:
281
- from: table_row
282
- under_section: Requirements
283
- required: false
284
- assert:
285
- columns:
286
- - ID
287
- - Kind
288
- - Source
289
- - Target
290
- min_rows: 1
291
- id_column: ID
292
- id_pattern: ^(StR|US|FR|NFR|IT|TC)-\d+$
293
- properties_table:
294
- from: table_row
295
- under_section: Properties
296
- required: false
297
- assert:
298
- columns:
299
- - Field
300
- - Type
301
- - Multiplicity
302
- - Constraints
303
- min_rows: 1
304
- properties_fence:
305
- from: code_block
306
- language: sysml
307
- under_section: Properties
308
- required: false
309
- multiple: false
310
- invariants:
311
- from: code_block
312
- language: ocl
313
- under_section: Invariants
314
- required: false
315
- multiple: true
316
229
  doc_kinds:
317
230
  - application-spec
318
- - master-requirements
319
231
  object_types: []
320
232
  lint_rules: []
@@ -9,7 +9,6 @@
9
9
  "mapping_version",
10
10
  "module",
11
11
  "kinds",
12
- "imported_types",
13
12
  "models"
14
13
  ],
15
14
  "properties": {
@@ -29,22 +28,6 @@
29
28
  "$ref": "#/$defs/kind"
30
29
  }
31
30
  },
32
- "imported_types": {
33
- "description": "Types this module references from each package semantic.imports pins. FR-035 types `imports` as package -> exact semver and carries no type list (agent-ix/quoin#339), so the list lives here.",
34
- "type": "object",
35
- "propertyNames": {
36
- "pattern": "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$"
37
- },
38
- "additionalProperties": {
39
- "type": "array",
40
- "minItems": 1,
41
- "uniqueItems": true,
42
- "items": {
43
- "type": "string",
44
- "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
45
- }
46
- }
47
- },
48
31
  "models": {
49
32
  "type": "object",
50
33
  "minProperties": 1,
package/mappings.yaml CHANGED
@@ -5,12 +5,6 @@
5
5
  # fills it, the Markdown form it reads, and whether that form round-trips
6
6
  # byte-for-byte (`lossless`).
7
7
  #
8
- # `imported_types` says which types this module references from each package
9
- # `manifest.yaml`'s `semantic.imports` pins. The FR-035 contract types `imports`
10
- # as package -> exact semver and has no place for a per-package type list
11
- # (agent-ix/quoin#339), so it is declared here, and the suite checks every
12
- # `ImportedTypeRef` against both: the package in the manifest, the type here.
13
- #
14
8
  # GENERATED by `scripts/build_mappings.py` from `manifest.yaml`, so a column
15
9
  # list, a locator name, or an id pattern is written once and cannot drift.
16
10
  # Edit that script, not this file. `make schemas-check` fails on any drift.
@@ -23,14 +17,6 @@ kinds:
23
17
  - sysml-fence
24
18
  - ocl-clause
25
19
  - provenance
26
- imported_types:
27
- agent-ix/spec-artifacts-iso:
28
- - StR
29
- - US
30
- - FR
31
- - NFR
32
- - IT
33
- - TC
34
20
  models:
35
21
  ApplicationSpec:
36
22
  schema: schemas/ApplicationSpec.json
@@ -260,127 +246,3 @@ models:
260
246
  locator: invariants
261
247
  language: ocl
262
248
  lossless: true
263
- MasterRequirements:
264
- schema: schemas/MasterRequirements.json
265
- artifact_type: MasterRequirements
266
- authority: markdown
267
- round_trip: derived
268
- dropped_frontmatter_keys:
269
- - component_type
270
- - depends_on
271
- - description
272
- - implementation_language
273
- - object
274
- - okf_version
275
- - org
276
- - security_critical
277
- - standards_alignment
278
- - tags
279
- properties:
280
- id:
281
- kind: frontmatter
282
- path:
283
- - id
284
- required: true
285
- lossless: false
286
- title:
287
- kind: frontmatter
288
- path:
289
- - title
290
- locator: title
291
- required: true
292
- lossless: false
293
- type:
294
- kind: frontmatter
295
- path:
296
- - type
297
- required: true
298
- lossless: false
299
- status:
300
- kind: frontmatter
301
- path:
302
- - status
303
- lossless: false
304
- relationships:
305
- kind: frontmatter
306
- path:
307
- - relationships
308
- lossless: false
309
- provenance:
310
- kind: provenance
311
- lossless: false
312
- purpose:
313
- kind: section
314
- heading: Purpose
315
- locator: purpose
316
- lossless: true
317
- required: true
318
- scope:
319
- kind: section
320
- heading: Scope
321
- locator: scope
322
- lossless: true
323
- systemOverview:
324
- kind: section
325
- heading: System Overview
326
- locator: system_overview
327
- lossless: true
328
- structure:
329
- kind: section
330
- heading: Structure
331
- locator: structure
332
- lossless: true
333
- requirementsArchitecture:
334
- kind: section
335
- heading: Requirements Architecture
336
- locator: requirements_architecture
337
- lossless: true
338
- references:
339
- kind: section
340
- heading: References
341
- locator: references
342
- lossless: true
343
- fields:
344
- kind: typed-table
345
- heading: Properties
346
- locator: properties_table
347
- columns:
348
- - Field
349
- - Type
350
- - Multiplicity
351
- - Constraints
352
- row_model: semantic-core FieldDecl
353
- cell_parses:
354
- Field: text
355
- Type: text
356
- Multiplicity: multiplicity
357
- Constraints: constraints
358
- alternate_form:
359
- kind: sysml-fence
360
- heading: Properties
361
- language: sysml
362
- locator: properties_fence
363
- lossless: false
364
- requirements:
365
- kind: typed-table
366
- heading: Requirements
367
- locator: requirements_table
368
- columns:
369
- - ID
370
- - Kind
371
- - Source
372
- - Target
373
- row_model: RequirementRef
374
- id_pattern: ^(StR|US|FR|NFR|IT|TC)-\d+$
375
- cell_parses:
376
- ID: id
377
- Kind: enum
378
- Source: imported-type-ref
379
- Target: text
380
- lossless: false
381
- invariants:
382
- kind: ocl-clause
383
- heading: Invariants
384
- locator: invariants
385
- language: ocl
386
- lossless: true
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/spec-artifacts-app",
3
- "version": "0.9.0",
4
- "description": "Filament Module: application/composite spec artifacts including master-requirements",
3
+ "version": "0.10.1",
4
+ "description": "Filament Module: application/composite spec artifacts (ApplicationSpec); master-requirements is imported from spec-artifacts-iso",
5
5
  "license": "AGPL-3.0-or-later",
6
6
  "author": "Agent IX <agents@agent-ix.dev>",
7
7
  "keywords": [
@@ -17,5 +17,5 @@
17
17
  "unevaluatedProperties": {
18
18
  "not": {}
19
19
  },
20
- "description": "A reference to a type another module owns. The reference form this module\npublishes: a module and a type name, never a copy of the imported type's\nfields, and never a cross-module `$ref` (FR-002-AC-10)."
20
+ "description": "A reference to a type another module owns. The reference form this module\npublishes: a module and a type name, never a copy of the imported type's\nfields."
21
21
  }
@@ -29,5 +29,29 @@
29
29
  "unevaluatedProperties": {
30
30
  "not": {}
31
31
  },
32
- "description": "One row of `## Requirements`: a requirement this composite rolls up. The\nrequirement's own fields belong to the module that owns its type; this record\ncarries only the reference."
32
+ "description": "One row of `## Requirements`: a requirement this composite rolls up. The\nrequirement's own fields belong to the module that owns its type; this record\ncarries only the reference.\n\n`$defs.isoRequirement` is the one cross-package `$ref` in the bundle: the\nrequirement types of `spec-artifacts-iso` this application aggregates. It sits\nin `$defs`, which no property references, because the engine rewrites every\n`$ref` under an imported package into a schema that accepts anything — placed on\n`source` it would weaken `source`, here it only counts the import as used.",
33
+ "$defs": {
34
+ "isoRequirement": {
35
+ "anyOf": [
36
+ {
37
+ "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-iso/StR.json"
38
+ },
39
+ {
40
+ "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-iso/US.json"
41
+ },
42
+ {
43
+ "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-iso/FR.json"
44
+ },
45
+ {
46
+ "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-iso/NFR.json"
47
+ },
48
+ {
49
+ "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-iso/IT.json"
50
+ },
51
+ {
52
+ "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-iso/TC.json"
53
+ }
54
+ ]
55
+ }
56
+ }
33
57
  }
@@ -1,80 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/MasterRequirements.json",
4
- "type": "object",
5
- "properties": {
6
- "id": {
7
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/ArtifactId.json"
8
- },
9
- "title": {
10
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/NonEmptyText.json"
11
- },
12
- "type": {
13
- "type": "string",
14
- "const": "MasterRequirements"
15
- },
16
- "status": {
17
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/ArtifactStatus.json"
18
- },
19
- "relationships": {
20
- "type": "array",
21
- "items": {
22
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Relationship.json"
23
- }
24
- },
25
- "provenance": {
26
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Provenance.json"
27
- },
28
- "purpose": {
29
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Section.json"
30
- },
31
- "scope": {
32
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Section.json"
33
- },
34
- "systemOverview": {
35
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Section.json"
36
- },
37
- "structure": {
38
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Section.json"
39
- },
40
- "requirementsArchitecture": {
41
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Section.json"
42
- },
43
- "references": {
44
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/Section.json"
45
- },
46
- "fields": {
47
- "type": "array",
48
- "items": {
49
- "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.2/FieldDecl.json"
50
- },
51
- "minItems": 1,
52
- "description": "The specification's identity attributes, declared as one typed row per\nfield in `## Properties`, or as the alternate `sysml` fence form of the\nsame declarations (quoin FR-071)."
53
- },
54
- "requirements": {
55
- "type": "array",
56
- "items": {
57
- "$ref": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/RequirementRef.json"
58
- }
59
- },
60
- "invariants": {
61
- "type": "array",
62
- "items": {
63
- "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.2/ClauseRef.json"
64
- },
65
- "minItems": 1
66
- }
67
- },
68
- "required": [
69
- "id",
70
- "title",
71
- "type",
72
- "relationships",
73
- "provenance",
74
- "purpose"
75
- ],
76
- "unevaluatedProperties": {
77
- "not": {}
78
- },
79
- "description": "The record of a `MasterRequirements` document: the front page of a\nspecification — its purpose, scope, and the set of requirements it rolls up.\n\nLike `ApplicationSpec`, it references the requirements it aggregates rather\nthan restating them, so the module that owns a requirement type stays the one\ndefinition of it."
80
- }
@@ -1,49 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "type": "object",
4
- "required": [
5
- "id",
6
- "title",
7
- "type"
8
- ],
9
- "additionalProperties": true,
10
- "properties": {
11
- "id": {
12
- "type": "string",
13
- "pattern": "^[A-Z]{2,4}-[0-9]+$"
14
- },
15
- "title": {
16
- "type": "string",
17
- "minLength": 1
18
- },
19
- "type": {
20
- "const": "MasterRequirements"
21
- },
22
- "object": {
23
- "type": "string"
24
- },
25
- "relationships": {
26
- "type": "array",
27
- "items": {
28
- "type": "object",
29
- "required": [
30
- "target",
31
- "type"
32
- ],
33
- "additionalProperties": false,
34
- "properties": {
35
- "target": {
36
- "type": "string",
37
- "pattern": "^ix://"
38
- },
39
- "type": {
40
- "type": "string"
41
- },
42
- "cardinality": {
43
- "type": "string"
44
- }
45
- }
46
- }
47
- }
48
- }
49
- }
@@ -1,104 +0,0 @@
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
- ```