@agent-ix/quoin 0.2.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.
Files changed (124) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +122 -0
  3. package/bin/quoin.js +8 -0
  4. package/default-modules.yaml +82 -0
  5. package/dist/catalog.d.ts +32 -0
  6. package/dist/catalog.d.ts.map +1 -0
  7. package/dist/cli-ClS52_Fm.js +436 -0
  8. package/dist/cli.d.ts +3 -0
  9. package/dist/cli.d.ts.map +1 -0
  10. package/dist/cli.js +2 -0
  11. package/dist/flows.d.ts +7 -0
  12. package/dist/flows.d.ts.map +1 -0
  13. package/dist/index.d.ts +6 -0
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/index.js +2 -0
  16. package/dist/modules.d.ts +10 -0
  17. package/dist/modules.d.ts.map +1 -0
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.d.ts.map +1 -0
  20. package/dist/write.d.ts +22 -0
  21. package/dist/write.d.ts.map +1 -0
  22. package/package.json +85 -0
  23. package/plugin.json +6 -0
  24. package/skills/spec-app-review/SKILL.md +51 -0
  25. package/skills/spec-app-review/references/checklist.md +194 -0
  26. package/skills/spec-dependency-analysis/SKILL.md +75 -0
  27. package/skills/spec-evidence-analysis/SKILL.md +78 -0
  28. package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
  29. package/skills/spec-ideation/SKILL.md +46 -0
  30. package/skills/spec-integrity-analysis/SKILL.md +47 -0
  31. package/skills/spec-matrix/SKILL.md +79 -0
  32. package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
  33. package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
  34. package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
  35. package/skills/spec-matrix/assets/test-matrix-example.md +97 -0
  36. package/skills/spec-matrix/assets/test-matrix-template.md +117 -0
  37. package/skills/spec-matrix/workflow-assets/dist/index.d.ts +146 -0
  38. package/skills/spec-matrix/workflow-assets/dist/index.d.ts.map +1 -0
  39. package/skills/spec-matrix/workflow-assets/dist/index.js +7655 -0
  40. package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts +6 -0
  41. package/skills/spec-matrix/workflow-assets/dist/invariants.d.ts.map +1 -0
  42. package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
  43. package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
  44. package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
  45. package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
  46. package/skills/spec-object-review/SKILL.md +125 -0
  47. package/skills/spec-object-review/references/object-type-guide.md +113 -0
  48. package/skills/spec-review/SKILL.md +41 -0
  49. package/skills/spec-review/references/checklist.md +50 -0
  50. package/skills/spec-review/workflow-assets/dist/index.d.ts +146 -0
  51. package/skills/spec-review/workflow-assets/dist/index.d.ts.map +1 -0
  52. package/skills/spec-review/workflow-assets/dist/index.js +7655 -0
  53. package/skills/spec-review/workflow-assets/dist/invariants.d.ts +6 -0
  54. package/skills/spec-review/workflow-assets/dist/invariants.d.ts.map +1 -0
  55. package/skills/spec-review/workflow-assets/skills/review/SKILL.md +35 -0
  56. package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +1 -0
  57. package/skills/spec-review/workflow-assets/skills/review/templates/report/default.md +30 -0
  58. package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +82 -0
  59. package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
  60. package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
  61. package/skills/spec-security-analysis/SKILL.md +84 -0
  62. package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
  63. package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
  64. package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
  65. package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
  66. package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
  67. package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
  68. package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
  69. package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
  70. package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
  71. package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
  72. package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
  73. package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
  74. package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
  75. package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
  76. package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
  77. package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
  78. package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
  79. package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
  80. package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
  81. package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
  82. package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
  83. package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
  84. package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
  85. package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
  86. package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
  87. package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
  88. package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
  89. package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
  90. package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
  91. package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
  92. package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
  93. package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
  94. package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
  95. package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
  96. package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
  97. package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
  98. package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
  99. package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
  100. package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
  101. package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
  102. package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
  103. package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
  104. package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
  105. package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
  106. package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
  107. package/skills/spec-security-analysis/references/soc2/index.md +46 -0
  108. package/skills/spec-security-analysis/references/standards-index.md +46 -0
  109. package/skills/spec-to-plan/SKILL.md +44 -0
  110. package/skills/spec-to-plan/references/step-1-analysis.md +58 -0
  111. package/skills/spec-to-plan/references/step-2-test-plan.md +37 -0
  112. package/skills/spec-to-plan/references/step-3-execution-plan.md +178 -0
  113. package/skills/spec-to-plan/workflow-assets/dist/index.d.ts +146 -0
  114. package/skills/spec-to-plan/workflow-assets/dist/index.d.ts.map +1 -0
  115. package/skills/spec-to-plan/workflow-assets/dist/index.js +7655 -0
  116. package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts +6 -0
  117. package/skills/spec-to-plan/workflow-assets/dist/invariants.d.ts.map +1 -0
  118. package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
  119. package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
  120. package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +43 -0
  121. package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +82 -0
  122. package/skills/specify/SKILL.md +69 -0
  123. package/skills/specify/assets/app-spec-template.md +143 -0
  124. package/skills/specify/assets/spec-template.md +299 -0
@@ -0,0 +1,6 @@
1
+ import { InvariantEvaluator } from '@agent-ix/workflow-core';
2
+ export declare const artifactFrontmatterValid: InvariantEvaluator;
3
+ export declare const artifactRelationshipsResolve: InvariantEvaluator;
4
+ export declare function clearProjectRegistryCache(): void;
5
+ export declare const specInvariants: Record<string, InvariantEvaluator>;
6
+ //# sourceMappingURL=invariants.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../src/invariants.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAqDjC,eAAO,MAAM,wBAAwB,EAAE,kBAqHtC,CAAC;AAIF,eAAO,MAAM,4BAA4B,EAAE,kBAiG1C,CAAC;AA4DF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAG7D,CAAC"}
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: spec-to-plan
3
+ description: Convert validated requirements into an implementation plan.
4
+ contributes:
5
+ workflows: ./workflows
6
+ ---
7
+
8
+ # /spec-to-plan
9
+
10
+ ## When To Use
11
+
12
+ Use this skill when accepted requirements should become ordered implementation work.
13
+
14
+ ## What It Does
15
+
16
+ Convert validated requirements into an implementation plan. The workflow definition is the source of truth for phases, gates, item schemas, recipes, and validation points.
17
+
18
+ ## Workflow Behavior
19
+
20
+ - Start from the workflow status and follow reported next actions.
21
+ - Record evidence items before advancing analysis, review, or validation phases.
22
+ - Use recipes for deterministic command chains, but preserve human gates for acceptance.
23
+ - Prefer templates for stable artifact creation and generic file editing for broad semantic rewrites.
24
+
25
+ ## Acceptance Criteria
26
+
27
+ - AC-1: Produces a plan that traces tasks back to requirement IDs.
28
+ - AC-2: Preserves dependencies, risks, and verification expectations in the plan.
29
+ - AC-3: Flags requirements that are not ready for planning instead of forcing tasks.
30
+
31
+ ## Boundaries
32
+
33
+ - Do not silently overwrite existing human-authored requirements artifacts.
34
+ - Do not invent missing facts, links, or evidence; record assumptions and gaps.
35
+ - Do not expand to adjacent spec operations unless the user request requires it or the workflow directs it.
@@ -0,0 +1 @@
1
+ export { specInvariants as invariants } from "../../../dist/index.js";
@@ -0,0 +1,43 @@
1
+ ---
2
+ type: implementation-plan
3
+ id: "{{items.plan_answers.plan.id}}"
4
+ title: "{{items.plan_answers.plan.title}}"
5
+ traces_to:
6
+ - "{{items.plan_answers.plan.requirement_ids}}"
7
+ ---
8
+
9
+ # {{items.plan_answers.plan.id}}: {{items.plan_answers.plan.title}}
10
+
11
+ ## Scope
12
+
13
+ This plan covers accepted requirements:
14
+
15
+ {{items.plan_answers.plan.requirement_ids}}
16
+
17
+ ## Readiness Notes
18
+
19
+ {{items.plan_answers.plan.readiness_notes}}
20
+
21
+ ## Work Breakdown
22
+
23
+ | Task | Requirement Trace | Outcome | Verification |
24
+ | ---- | ------------------------------------------- | ------------------------------ | ---------------------------------------------------- |
25
+ | T-1 | {{items.plan_answers.plan.requirement_ids}} | Define implementation changes. | Tests or review evidence linked to each requirement. |
26
+ | T-2 | {{items.plan_answers.plan.requirement_ids}} | Implement scoped changes. | Passing automated checks. |
27
+ | T-3 | {{items.plan_answers.plan.requirement_ids}} | Update verification evidence. | Requirements matrix or review report updated. |
28
+
29
+ ## Dependencies
30
+
31
+ - Confirm every traced requirement is accepted and implementation-ready.
32
+ - Resolve readiness notes before scheduling blocked work.
33
+
34
+ ## Risks
35
+
36
+ - Requirements with weak acceptance criteria may produce vague tasks.
37
+ - Missing trace evidence may cause implementation work to drift from the spec.
38
+
39
+ ## Acceptance Criteria
40
+
41
+ - Every task traces to at least one requirement id.
42
+ - Every traced requirement has an implementation or verification task.
43
+ - Blockers are explicit and not hidden inside task descriptions.
@@ -0,0 +1,82 @@
1
+ name: to-plan
2
+ version: 0.1.0
3
+ description: Convert accepted requirements into a traced implementation plan.
4
+ initialPhase: intake
5
+ phases:
6
+ - { name: intake }
7
+ - { name: evidence_recorded }
8
+ - { name: plan_drafted }
9
+ - { name: validated }
10
+ - { name: accepted, terminal: true }
11
+ transitions:
12
+ - from: intake
13
+ to: evidence_recorded
14
+ invariants:
15
+ - "interview.complete:plan"
16
+ defaultGate: auto
17
+ - from: evidence_recorded
18
+ to: plan_drafted
19
+ invariants: []
20
+ defaultGate: auto
21
+ - from: plan_drafted
22
+ to: validated
23
+ invariants:
24
+ - "artifact.frontmatter_valid:implementation_plan"
25
+ defaultGate: auto
26
+ - from: validated
27
+ to: accepted
28
+ invariants: []
29
+ defaultGate: hitl
30
+ itemSchemas:
31
+ plan_answers: {}
32
+ ImplementationPlanSchema:
33
+ required: [type, id, title, traces_to]
34
+ properties:
35
+ type: { type: string }
36
+ id: { type: string }
37
+ title: { type: string }
38
+ traces_to: { type: array }
39
+ linkSchemas: {}
40
+ interviews:
41
+ plan:
42
+ itemType: plan_answers
43
+ completenessRule: all_required
44
+ questions:
45
+ - key: artifact_id
46
+ prompt: "Plan id, for example PLAN-001."
47
+ type: text
48
+ required: true
49
+ - key: slug
50
+ prompt: "Filename slug without the plan id."
51
+ type: text
52
+ required: true
53
+ - key: title
54
+ prompt: "Implementation plan title."
55
+ type: text
56
+ required: true
57
+ - key: requirement_ids
58
+ prompt: "Comma-separated accepted requirement ids this plan traces to."
59
+ type: text
60
+ required: true
61
+ - key: readiness_notes
62
+ prompt: "Known blockers, assumptions, or readiness notes."
63
+ type: text
64
+ required: true
65
+ artifactTemplates:
66
+ implementation_plan:
67
+ source: templates/implementation-plan/default.md
68
+ target: spec/plans/${items.plan_answers.plan.id}-${items.plan_answers.plan.slug}.md
69
+ phase: plan_drafted
70
+ frontmatterSchema: ImplementationPlanSchema
71
+ recipes:
72
+ draft-and-validate:
73
+ description: Record planning inputs, draft the traced plan, validate it, then stop at acceptance.
74
+ steps:
75
+ - command: advance
76
+ to: evidence_recorded
77
+ - command: advance
78
+ to: plan_drafted
79
+ - command: advance
80
+ to: validated
81
+ - command: advance
82
+ to: accepted
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: specify
3
+ description: Create or update spec files using quoin catalog authoring packs and Quire validation.
4
+ ---
5
+
6
+ # Specify
7
+
8
+ Use this skill when turning an agreed design, feature, or change request into
9
+ spec artifacts and supporting spec objects.
10
+
11
+ ## Process
12
+
13
+ 1. Identify the repository that owns the spec files.
14
+ 2. Identify every artifact and object type that will be created or edited.
15
+ 3. Run `quoin write <repo_dir> --types <type[,type...]>` once for the full set of types.
16
+ 4. Use the returned skeletons, schemas, module roots, and examples as the authoring contract.
17
+ 5. Author or edit the files directly in the target repo.
18
+ 6. Run `quire validate <glob> [glob2 ...]` over the changed spec scope.
19
+ 7. Fix validation errors before moving to review, matrix, or planning work.
20
+
21
+ ## Type Selection
22
+
23
+ Request all needed types together so the agent does not repeatedly fetch the
24
+ same templates.
25
+
26
+ Examples:
27
+
28
+ ```bash
29
+ quoin write . --types FR,domain,entity
30
+ quoin write ../service --types StR,US,FR,NFR
31
+ quoin write . --types process,configuration,value_object
32
+ ```
33
+
34
+ Type lookup is catalog-driven and case-insensitive. Types may come from bundled
35
+ `spec-artifacts-*`, bundled `spec-objects-*`, user-installed modules, or
36
+ community modules.
37
+
38
+ ## Authoring Rules
39
+
40
+ - Let frontmatter identify exactly what each file is. The discriminator field is
41
+ `type` (e.g. `type: FR`, `type: master-requirements`); it names the archetype the
42
+ document conforms to.
43
+ - Use catalog skeletons and schemas rather than memory.
44
+ - Keep workflow definitions out of artifact/object type vocabularies.
45
+ - Validate every created or edited artifact with Quire.
46
+ - Use `spec-review` after validation for quality, consistency, and completeness review.
47
+
48
+ ## Reserved OKF Files
49
+
50
+ `spec-artifacts-iso` ships two reserved archetypes for the OKF folder structure;
51
+ author them like any other type:
52
+
53
+ - `index.md` — `type: index`, body is a `## Contents` link list pointing at the
54
+ artifacts in the folder.
55
+ - `log.md` — `type: log`, body is a `## History` of changes to the folder's specs.
56
+
57
+ ## Common Spec Layout
58
+
59
+ ```text
60
+ spec/
61
+ ├── spec.md
62
+ ├── stakeholder/
63
+ ├── usecase/
64
+ ├── functional/
65
+ ├── non-functional/
66
+ ├── integration/
67
+ ├── matrix/
68
+ └── analysis/
69
+ ```
@@ -0,0 +1,143 @@
1
+ ---
2
+ type: master-requirements
3
+ name: <app-name>
4
+ org: <your-org>
5
+ component_type: application
6
+ tags: []
7
+ implementation_language: null
8
+ depends_on:
9
+ # List all component repos this application owns
10
+ # - service-one
11
+ # - library-one
12
+ standards_alignment:
13
+ - iso-iec-ieee-29148
14
+ security_critical: false
15
+ ---
16
+ # Master Requirements Specification
17
+ ## <App Name>
18
+
19
+ ### 1. Purpose
20
+
21
+ <!-- 2-3 sentences: What problem does this application solve? Who does it serve?
22
+ Be specific — avoid restating the component names. -->
23
+
24
+ ### 2. Scope
25
+
26
+ This specification defines the **application-level** domain, encompassing end-to-end processes that span multiple component repositories. Individual component behavior is specified in each component's own `spec/` directory; this document defines how they compose into a complete system.
27
+
28
+ ### 3. System Overview
29
+
30
+ #### 3.1 Component Registry
31
+
32
+ <!-- One row per component repo. Distinguish services vs libraries. -->
33
+
34
+ | Component | Type | Repo | Role |
35
+ |-----------|------|------|------|
36
+ | <!-- name --> | <!-- fastapi-service / python-lib / react-lib / etc --> | `<!-- repo-name -->` | <!-- What it does in 1 sentence --> |
37
+
38
+ #### 3.2 Dependency Graph
39
+
40
+ <!-- Required: Show how components connect. Use color styles to distinguish
41
+ services (red), libraries (green), SDKs (orange), UI (purple). -->
42
+
43
+ ```mermaid
44
+ graph TD
45
+ A[ComponentA] --> B[ComponentB]
46
+
47
+ style A fill:#e74c3c,color:#fff
48
+ style B fill:#2ecc71,color:#fff
49
+ ```
50
+
51
+ ### 4. Architecture Rationale
52
+
53
+ <!-- Required: Explain WHY the architecture looks the way it does.
54
+ One ADR entry per major structural decision. -->
55
+
56
+ #### ADR-001: <!-- Decision Title -->
57
+
58
+ **Decision**: <!-- What was decided. One sentence. -->
59
+
60
+ **Rationale**: <!-- Why? What problem does this solve? -->
61
+
62
+ **Alternatives considered**: <!-- What else was evaluated and why it was rejected. -->
63
+
64
+ ### 5. Stakeholder Requirements
65
+
66
+ | ID | Title | Artifact |
67
+ |----|-------|----------|
68
+ | StR-001 | <!-- Title --> | [StR-001](stakeholder/StR-001-<slug>.md) |
69
+
70
+ ### 6. User Stories
71
+
72
+ | ID | Title | Role | Artifact |
73
+ |----|-------|------|----------|
74
+ | US-001 | <!-- Title --> | <!-- Role --> | [US-001](usecase/US-001-<slug>.md) |
75
+
76
+ ### 7. Functional Requirements
77
+
78
+ <!-- Application specs MUST include these object types:
79
+ - domain: Bounded context, ER diagram (FR-001)
80
+ - process: One per major cross-service workflow
81
+ - configuration: Shared config across services
82
+ - integration: Consumer contract (how to integrate with this app) -->
83
+
84
+ | ID | Title | Object Type | Artifact |
85
+ |----|-------|-------------|----------|
86
+ | FR-001 | <!-- App --> Domain | domain | [FR-001](functional/FR-001-<slug>-domain.md) |
87
+ | FR-002 | <!-- Primary Workflow --> Process | process | [FR-002](functional/FR-002-<slug>-process.md) |
88
+ | FR-XXX | <!-- App --> Configuration | configuration | [FR-XXX](functional/FR-XXX-configuration.md) |
89
+ | FR-XXX | Consumer Integration Contract | integration | [FR-XXX](functional/FR-XXX-consumer-integration.md) |
90
+
91
+ ### 8. Non-Functional Requirements
92
+
93
+ <!-- Application specs MUST include these three NFRs:
94
+ - Security Constraints (crypto, transport, error handling)
95
+ - System Reliability (SLA, p99 latency, scale limits, RTO/RPO)
96
+ - Deployment Topology (namespace, ingress, discovery, secrets) -->
97
+
98
+ | ID | Title | Artifact |
99
+ |----|-------|----------|
100
+ | NFR-001 | Security Constraints | [NFR-001](non-functional/NFR-001-security.md) |
101
+ | NFR-002 | System Reliability | [NFR-002](non-functional/NFR-002-reliability.md) |
102
+ | NFR-003 | Deployment Topology | [NFR-003](non-functional/NFR-003-deployment.md) |
103
+
104
+ ### 9. Domain Model
105
+
106
+ See [FR-001 <!-- App --> Domain](functional/FR-001-<slug>-domain.md) for the bounded context definition, entity relationships, and ER diagram.
107
+
108
+ ### 10. Scope Boundaries
109
+
110
+ <!-- Required: Explicitly list what this application does NOT do.
111
+ These are deliberate exclusions, not future work. -->
112
+
113
+ | Out of Scope | Rationale |
114
+ |---|---|
115
+ | <!-- Feature --> | <!-- Why deliberately excluded --> |
116
+
117
+ ### 11. Security Model
118
+
119
+ <!-- Required: Define the actor model and trust hierarchy.
120
+ What roles exist? What can each role do? -->
121
+
122
+ #### Actor Roles
123
+
124
+ | Role | Description | Assigned By |
125
+ |------|-------------|-------------|
126
+ | `anonymous` | Unauthenticated caller | Default |
127
+ | `user` | Authenticated user | Auth system |
128
+ | `admin` | Administrator | Operator |
129
+ | `operator` | Infrastructure operator | Out-of-band |
130
+
131
+ #### Trust Boundaries
132
+
133
+ <!-- List capabilities and which roles can exercise them. -->
134
+
135
+ | Capability | anonymous | user | admin | operator |
136
+ |---|---|---|---|---|
137
+ | <!-- action --> | — | ✅ | ✅ | ✅ |
138
+
139
+ ### 12. References
140
+
141
+ | Standard | Description |
142
+ |----------|-------------|
143
+ | ISO/IEC/IEEE 29148 | Requirements engineering standard |
@@ -0,0 +1,299 @@
1
+ ---
2
+ type: master-requirements
3
+ name: <component-name> # Required: repo/component name
4
+ org: <your-org> # Required: owning organization
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
+ ---