@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-review
3
+ description: Run a composite specification review.
4
+ contributes:
5
+ workflows: ./workflows
6
+ ---
7
+
8
+ # /spec-review
9
+
10
+ ## When To Use
11
+
12
+ Use this skill for a full or multi-artifact spec review before implementation, release, or migration.
13
+
14
+ ## What It Does
15
+
16
+ Run a composite specification review. 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: Reviews structural integrity, traceability, coverage, and readiness across selected artifacts.
28
+ - AC-2: Records evidence items before validation.
29
+ - AC-3: Stops at acceptance with findings and recommended next workflows rather than making broad edits.
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,30 @@
1
+ ---
2
+ type: spec-review
3
+ id: "{{items.operation_request.request.artifact_id}}"
4
+ title: "{{items.operation_request.request.title}}"
5
+ scope: "{{items.operation_request.request.scope}}"
6
+ ---
7
+
8
+ # {{items.operation_request.request.artifact_id}}: {{items.operation_request.request.title}}
9
+
10
+ ## Operation
11
+
12
+ Run a composite specification review.
13
+
14
+ ## Scope
15
+
16
+ {{items.operation_request.request.scope}}
17
+
18
+ ## Evidence
19
+
20
+ {{items.operation_request.request.evidence}}
21
+
22
+ ## Findings
23
+
24
+ {{items.operation_request.request.findings}}
25
+
26
+ ## Acceptance Criteria
27
+
28
+ - Evidence is recorded before conclusions.
29
+ - Findings reference concrete spec paths, requirement ids, or graph objects where available.
30
+ - Follow-up work is expressed as recommended next workflows rather than hidden edits.
@@ -0,0 +1,82 @@
1
+ name: review
2
+ version: 0.1.0
3
+ description: Run a composite specification review.
4
+ initialPhase: intake
5
+ phases:
6
+ - { name: intake }
7
+ - { name: evidence_recorded }
8
+ - { name: report_rendered }
9
+ - { name: validated }
10
+ - { name: accepted, terminal: true }
11
+ transitions:
12
+ - from: intake
13
+ to: evidence_recorded
14
+ invariants:
15
+ - "interview.complete:request"
16
+ defaultGate: auto
17
+ - from: evidence_recorded
18
+ to: report_rendered
19
+ invariants: []
20
+ defaultGate: auto
21
+ - from: report_rendered
22
+ to: validated
23
+ invariants:
24
+ - "artifact.frontmatter_valid:report"
25
+ defaultGate: auto
26
+ - from: validated
27
+ to: accepted
28
+ invariants: []
29
+ defaultGate: hitl
30
+ itemSchemas:
31
+ operation_request: {}
32
+ OperationReportSchema:
33
+ required: [type, id, title, scope]
34
+ properties:
35
+ type: { type: string }
36
+ id: { type: string }
37
+ title: { type: string }
38
+ scope: { type: string }
39
+ linkSchemas: {}
40
+ interviews:
41
+ request:
42
+ itemType: operation_request
43
+ completenessRule: all_required
44
+ questions:
45
+ - key: artifact_id
46
+ prompt: "Report id, for example REPORT-001."
47
+ type: text
48
+ required: true
49
+ - key: title
50
+ prompt: "Report title."
51
+ type: text
52
+ required: true
53
+ - key: scope
54
+ prompt: "Spec paths, requirement ids, or graph scope to inspect."
55
+ type: text
56
+ required: true
57
+ - key: evidence
58
+ prompt: "Evidence sources used for this operation."
59
+ type: text
60
+ required: true
61
+ - key: findings
62
+ prompt: "Findings, gaps, or result summary."
63
+ type: text
64
+ required: true
65
+ artifactTemplates:
66
+ report:
67
+ source: templates/report/default.md
68
+ target: spec/reports/review/${items.operation_request.request.artifact_id}.md
69
+ phase: report_rendered
70
+ frontmatterSchema: OperationReportSchema
71
+ recipes:
72
+ run-to-review:
73
+ description: Record inputs, render the operation report, validate it, then stop at acceptance.
74
+ steps:
75
+ - command: advance
76
+ to: evidence_recorded
77
+ - command: advance
78
+ to: report_rendered
79
+ - command: advance
80
+ to: validated
81
+ - command: advance
82
+ to: accepted
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: spec-risk-complexity-analysis
3
+ description: Identify technical risks and volatility in requirements before tasking.
4
+ ---
5
+
6
+ # Risk & Complexity Analysis
7
+
8
+ Surface the requirements that are most likely to fail, slip, or churn — so they can be sliced smaller, prototyped first, or hedged with extra verification.
9
+
10
+ ## When to use
11
+
12
+ - After dependency, scope, and evidence analysis but before `spec-to-plan` decomposes tasks.
13
+ - After any major external change (new compliance regime, new SLA, new vendor).
14
+
15
+ ## Risk dimensions
16
+
17
+ Each FR/StR/NFR is scored on two independent axes.
18
+
19
+ ### Technical risk
20
+
21
+ Flag a requirement as **high risk** if it involves any of:
22
+
23
+ - **Novel technology** — first time this team or system uses it (new database engine, new protocol, new language runtime).
24
+ - **Concurrency / distributed coordination** — multi-writer state, consensus, leader election, exactly-once semantics.
25
+ - **Security or compliance constraint** — regulated data, cryptographic primitives, auth boundary changes.
26
+ - **Hard performance guarantee** — quantified latency/throughput/availability bounds (p99, RPO/RTO).
27
+
28
+ Otherwise medium (one of the above is tangentially involved) or low.
29
+
30
+ ### Volatility
31
+
32
+ Flag a requirement as **high volatility** if it is likely to change due to:
33
+
34
+ - **Policy evolution** — regulatory or org policy not yet stable.
35
+ - **External contracts** — depends on a third-party API we don't control.
36
+ - **Product discovery** — UX or business rules expected to shift as users are observed.
37
+
38
+ Otherwise medium or low.
39
+
40
+ ## Process
41
+
42
+ 1. **Score** every FR/StR/NFR on both axes.
43
+ 2. **Mitigate high-risk, low-volatility** items by spiking/prototyping early and adding contract/property tests.
44
+ 3. **Mitigate high-volatility** items by slicing into smaller iterative tasks and avoiding deep dependencies on them.
45
+ 4. **Cross-check failure domains** — see `spec-failure-domain-analysis` for extension, identity, purity, and topology gaps that *also* increase risk.
46
+ 5. **Produce the risk register** below.
47
+
48
+ ## Deliverable template
49
+
50
+ Record output in `spec/analysis/risk-register.md`.
51
+
52
+ ```markdown
53
+ # Risk Register
54
+
55
+ | Req | Tech Risk | Volatility | Drivers | Mitigation |
56
+ |-----|-----------|------------|---------|------------|
57
+ | FR-018 | High | Low | Distributed lock, exactly-once payout | Spike + property tests + contract test against ledger |
58
+ | FR-022 | Medium | High | UX flow under product discovery | Slice into 3 iterative tasks; avoid downstream coupling |
59
+ | NFR-005 | High | Low | p99 < 50ms across 100rps | Load test as quality gate; budget allocated in FR-018 |
60
+ | FR-030 | Low | High | Tax rules change quarterly | Move rule table behind config; ship update path |
61
+
62
+ ## Top hazards
63
+
64
+ 1. FR-018 — distributed exactly-once payout (see mitigation above).
65
+ 2. NFR-005 — perf budget owns FR-018's success; if perf fails, payout slips.
66
+
67
+ ## Failure-domain gaps
68
+
69
+ See `spec-failure-domain-analysis` deliverable. Open gaps: none / list FR IDs.
70
+ ```
71
+
72
+ ## Acceptance Criteria
73
+
74
+ - Every FR/StR/NFR has both axes scored (no blanks).
75
+ - Every High on either axis has a named mitigation.
76
+ - The "Top hazards" section names the 3–5 items the team should review live before plan generation.
77
+ - Cross-reference to `spec-failure-domain-analysis` deliverable is present and current.
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: spec-scope-boundary-analysis
3
+ description: Define system boundaries and allocate responsibilities for ISO-style specifications.
4
+ ---
5
+
6
+ # Scope & Boundary Analysis
7
+
8
+ Define what the system owns, what it consumes from outside, and which component owns each requirement.
9
+
10
+ ## When to use
11
+
12
+ - Once the StR/FR set is stable but before tasking.
13
+ - When a new external dependency or component is introduced.
14
+ - During `spec-app-review` for application-type specs that span multiple components.
15
+
16
+ ## Process
17
+
18
+ 1. **System Boundary Definition.**
19
+ - Enumerate in-scope responsibilities (what this system guarantees).
20
+ - Enumerate external dependencies (what it consumes and trusts).
21
+ - For each dependency, mark whether its behavior is **assumed** (we don't verify it) or **guaranteed** (we verify via contract test).
22
+
23
+ 2. **Responsibility Allocation.** For each FR/StR/NFR, assign:
24
+ - An **owning component or subsystem**.
25
+ - A **responsibility class**:
26
+ - `core` — domain logic specific to this system.
27
+ - `infrastructure` — persistence, transport, scheduling, storage.
28
+ - `cross-cutting` — auth, logging, metrics, error handling, audit.
29
+
30
+ This step defines *where* work belongs, not *how* it is done.
31
+
32
+ 3. **Produce the deliverable** using the template below.
33
+
34
+ ## Deliverable template
35
+
36
+ Record output in `spec/analysis/scope-boundary.md`.
37
+
38
+ ```markdown
39
+ # Scope & Boundary Analysis
40
+
41
+ ## System Context
42
+
43
+ ​```mermaid
44
+ flowchart LR
45
+ user([User])
46
+ ext1[(External: Identity Provider)]
47
+ ext2[(External: Audit Log Sink)]
48
+ subgraph SUT [System Under Spec]
49
+ api[API Gateway]
50
+ core[Core Service]
51
+ db[(Postgres)]
52
+ end
53
+ user --> api --> core --> db
54
+ core -->|assumed| ext1
55
+ core -->|guaranteed via contract test| ext2
56
+ ​```
57
+
58
+ ## In-Scope Responsibilities
59
+
60
+ - Authenticate and authorize all inbound API requests.
61
+ - Persist domain entities X, Y, Z with the schema defined in FR-010..FR-012.
62
+ - Emit audit events on every state transition.
63
+
64
+ ## External Dependencies
65
+
66
+ | Dependency | Type | Assumed or Guaranteed | Contract |
67
+ |------------|------|------------------------|----------|
68
+ | Identity Provider | OIDC | Assumed | Provider's published spec |
69
+ | Audit Log Sink | HTTP | Guaranteed | IT-005 contract test |
70
+
71
+ ## Responsibility Allocation
72
+
73
+ | Requirement | Owning Component | Class |
74
+ |-------------|------------------|-------|
75
+ | FR-001 (auth middleware) | API Gateway | cross-cutting |
76
+ | FR-010 (user entity) | Core Service | core |
77
+ | FR-020 (postgres migration) | Core Service | infrastructure |
78
+ | NFR-003 (request log) | API Gateway | cross-cutting |
79
+ ```
80
+
81
+ ## Acceptance Criteria
82
+
83
+ - Every FR/StR/NFR is assigned exactly one owning component and one responsibility class.
84
+ - Every external dependency is marked `assumed` or `guaranteed` with a named contract.
85
+ - The system context diagram shows every external actor named in the spec.
86
+ - No "TBD" entries in the allocation table.
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: spec-security-analysis
3
+ description: Analyze specifications and implementations to identify applicable security standards and generate compliance traceability documentation.
4
+ ---
5
+
6
+ # Security Compliance Analysis
7
+
8
+ Analyze a component's specification and implementation to generate comprehensive security compliance traceability. Apply ALL security standards for maximum coverage - overlapping controls strengthen rather than conflict.
9
+
10
+ ## Mandatory Standards
11
+
12
+ Apply ALL of these standards to EVERY analysis (scope varies by component function):
13
+
14
+ | Standard | Version | Scope |
15
+ |----------|---------|-------|
16
+ | AICPA SOC 2 | 2017 TSC | Trust Services Criteria |
17
+ | ISO/IEC 27001 | 2022 | Annex A Controls |
18
+ | NIST SP 800-53 | Rev 5.2.0 | Security & Privacy Controls |
19
+ | OWASP ASVS | 5.0.0 | Application Security Verification |
20
+ | EU GDPR | 2016/679 | Data Protection Articles |
21
+
22
+ ## Process
23
+
24
+ 1. **Gather Context**
25
+ - Read `spec/spec.md` (if exists)
26
+ - Scan implementation for security-relevant patterns (auth, data, API, logging)
27
+ - Identify component type and function
28
+
29
+ 2. **Identify Applicable Controls**
30
+ - Read [references/standards-index.md](references/standards-index.md) for standard selection
31
+ - Select relevant chapters from each standard's index:
32
+ - [soc2/index.md](references/soc2/index.md) → CC1-CC9 categories
33
+ - [iso27001/index.md](references/iso27001/index.md) → A5-A8 themes
34
+ - [nist-800-53/index.md](references/nist-800-53/index.md) → Control families
35
+ - [owasp-asvs/index.md](references/owasp-asvs/index.md) → V1-V14 areas
36
+ - [gdpr/index.md](references/gdpr/index.md) → Chapters II-V
37
+ - Use index decision guides to choose specific chapters to investigate
38
+ - Reference [component-type-mapping.md](references/component-type-mapping.md) for scope guidance
39
+ - **[REQUIRED]** Verify identified controls against official FREE sources:
40
+ - NIST 800-53: https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final (US Gov - fully open)
41
+ - OWASP ASVS: https://github.com/OWASP/ASVS (CC BY-SA 4.0 - fully open)
42
+ - GDPR: https://eur-lex.europa.eu/eli/reg/2016/679/oj (EU Law - fully open)
43
+ - SOC 2 TSC: https://en.wikipedia.org/wiki/SOC_2 (reference summary - no login)
44
+ - ISO 27001: https://en.wikipedia.org/wiki/ISO/IEC_27001 (control list - no login)
45
+ - Local references are summaries; use web search for specific control details
46
+
47
+ 3. **Map Controls to Requirements**
48
+ - Link each applicable control to existing FR/NFR/StR requirements
49
+ - Identify gaps where controls lack requirement coverage
50
+ - Document requirement-to-control bidirectional traceability
51
+
52
+ 4. **Define Scope Boundaries**
53
+ - Identify controls outside component scope
54
+ - Assign responsible component for out-of-scope controls
55
+ - Document explicitly what is NOT covered and why
56
+
57
+ 5. **Generate Output**
58
+ - Use template: [assets/security-analysis-template.md](assets/security-analysis-template.md)
59
+ - Output as Section 19 "Compliance Standards Traceability" in `spec/spec.md`
60
+ - Example: [assets/security-analysis-example.md](assets/security-analysis-example.md)
61
+
62
+ ## Output Sections
63
+
64
+ - **19.1 Targeted Standards**: All 5 mandatory standards with version and scope
65
+ - **19.2 Control Mapping**: Control ID → Standard → Name → Component Requirement
66
+ - **19.3 GDPR Compliance**: Specific GDPR article coverage
67
+ - **19.4 Audit Support Controls**: Cross-standard audit and logging controls
68
+ - **19.5 Out of Scope**: Controls outside component boundary with responsible component
69
+
70
+ ## Rules
71
+
72
+ - Apply ALL standards - comprehensive coverage trumps minimal compliance
73
+ - Every control mapping MUST reference specific FR/NFR/StR identifiers
74
+ - Overlapping controls from multiple standards reinforce coverage
75
+ - Out-of-scope controls MUST identify the responsible component
76
+ - Gap identification is required - missing control coverage is a finding
77
+
78
+ ## References
79
+
80
+ - Template: [assets/security-analysis-template.md](assets/security-analysis-template.md)
81
+ - Example: [assets/security-analysis-example.md](assets/security-analysis-example.md)
82
+ - Standards Index: [references/standards-index.md](references/standards-index.md)
83
+ - Component Mapping: [references/component-type-mapping.md](references/component-type-mapping.md)
84
+
@@ -0,0 +1,89 @@
1
+ # Example: py-permissions Security Compliance Traceability
2
+
3
+ This example shows the complete Section 19 from the py-permissions library specification.
4
+
5
+ ---
6
+
7
+ ## 19. Compliance Standards Traceability
8
+
9
+ This specification targets alignment with the following industry security and privacy standards.
10
+
11
+ ### 19.1 Targeted Standards
12
+
13
+ | Standard | Version | Scope | Region |
14
+ |----------|---------|-------|--------|
15
+ | AICPA SOC 2 | 2017 TSC | CC6 (Logical Access Controls) | Global |
16
+ | ISO/IEC 27001 | 2022 | Annex A.9 (Access Control) | Global |
17
+ | NIST SP 800-53 | Rev 5 | AC Family (Access Control) | US Federal |
18
+ | OWASP ASVS | 4.0 | V4 (Access Control Verification) | Global |
19
+ | EU GDPR | 2016/679 | Articles 25, 32 (Security of Processing) | EU/EEA |
20
+
21
+ ### 19.2 Control Mapping
22
+
23
+ | Control ID | Standard | Control Name | py-permissions Requirement |
24
+ |------------|----------|--------------|---------------------------|
25
+ | CC6.1 | SOC2 | Logical Access Security | FR-001, FR-002, FR-008, FR-009 |
26
+ | CC6.2 | SOC2 | User Registration/Authorization | FR-014 (Role Schema) |
27
+ | CC6.3 | SOC2 | Access Modification/Removal | FR-008 (RBAC), FR-014 |
28
+ | CC6.6 | SOC2 | Boundary Protection | FR-007 (Org Tenancy) |
29
+ | CC7.2 | SOC2 | Security Event Monitoring | FR-013 (Audit Logging) |
30
+ | A.9.1.1 | ISO 27001 | Access Control Policy | StR-001 |
31
+ | A.9.2.3 | ISO 27001 | Privileged Access Management | FR-008, FR-010 |
32
+ | A.9.2.5 | ISO 27001 | Review of User Access Rights | FR-015 (Permission Query) |
33
+ | A.9.4.1 | ISO 27001 | Information Access Restriction | FR-005, FR-003 |
34
+ | A.12.4.1 | ISO 27001 | Event Logging | FR-013 |
35
+ | AC-2 | NIST | Account Management | FR-014 |
36
+ | AC-3 | NIST | Access Enforcement | FR-001, FR-002 |
37
+ | AC-5 | NIST | Separation of Duties | FR-008 (RBAC) |
38
+ | AC-6 | NIST | Least Privilege | FR-005, FR-008 |
39
+ | AU-2 | NIST | Audit Events | FR-013 |
40
+ | 4.1.1 | ASVS | Access Control Model | FR-008, FR-009 |
41
+ | 4.2.1 | ASVS | Sensitive Data Access Control | FR-005, FR-007 |
42
+
43
+ ### 19.3 GDPR Compliance
44
+
45
+ | GDPR Article | Requirement | py-permissions Coverage |
46
+ |--------------|-------------|------------------------|
47
+ | Art. 25(1) | Data Protection by Design | FR-008 (RBAC), FR-009 (ABAC), NFR-002 (Fail-Safe) |
48
+ | Art. 25(2) | Data Protection by Default | FR-005 (Resource-Level), FR-003 (List Filtering) |
49
+ | Art. 32(1)(b) | Confidentiality/Integrity | FR-007 (Org Tenancy), FR-002 (Enforcement) |
50
+ | Art. 32(1)(d) | Regular Testing | NFR-001, NFR-003, NFR-004 (Verification) |
51
+ | Art. 32(4) | Authorized Processing Only | FR-001, FR-002, FR-013 (Audit) |
52
+
53
+ Key GDPR principles addressed:
54
+ - **Least Privilege**: FR-005, FR-008 enforce minimum necessary access
55
+ - **Access Logging**: FR-013 provides audit trail for Art. 30 records
56
+ - **Multi-Tenancy**: FR-007 ensures organization isolation (data controller boundaries)
57
+
58
+ ### 19.4 Audit Support Controls
59
+
60
+ | Control Requirement | Standard Reference | py-permissions Coverage |
61
+ |--------------------|-------------------|------------------------|
62
+ | Audit Logging | SOC2 CC7.2, ISO A.12.4, NIST AU-2 | FR-013 |
63
+ | Log Integrity | NIST AU-9 | FR-013-CON-2 |
64
+ | Fail-Safe Access | NIST AC-7, ISO A.9.4.2, GDPR Art. 32 | NFR-002 |
65
+ | Retention Compatibility | SOC2 CC7.3, ISO A.12.4.1, GDPR Art. 30 | NFR-005 |
66
+
67
+ ### 19.5 Out of Scope
68
+
69
+ The following controls are outside py-permissions scope:
70
+
71
+ | Control | Description | Responsible Component |
72
+ |---------|-------------|----------------------|
73
+ | CC6.4, CC6.5 | Physical Access/Asset Disposal | Infrastructure |
74
+ | A.9.2.1, A.9.2.2 | User Registration/Provisioning | Auth Service |
75
+ | AC-17, AC-18 | Remote/Wireless Access | Network Layer |
76
+ | GDPR Art. 17 | Right to Erasure | Data Service Layer |
77
+ | GDPR Art. 20 | Data Portability | Data Service Layer |
78
+
79
+ ---
80
+
81
+ ## Key Observations
82
+
83
+ This example demonstrates:
84
+
85
+ 1. **Comprehensive Coverage**: All 5 mandatory standards included with specific scopes
86
+ 2. **Bidirectional Traceability**: Each control maps to specific FR/NFR/StR identifiers
87
+ 3. **Overlapping Controls**: Multiple standards covering same area (e.g., Audit Logging) strengthens coverage
88
+ 4. **Clear Boundaries**: Out-of-scope controls explicitly assigned to responsible components
89
+ 5. **GDPR Principles**: Extracted and documented for EU compliance visibility
@@ -0,0 +1,73 @@
1
+ # Section 19: Compliance Standards Traceability Template
2
+
3
+ Use this template to generate the security compliance traceability section for `spec/spec.md`.
4
+
5
+ ---
6
+
7
+ ## 19. Compliance Standards Traceability
8
+
9
+ This specification targets alignment with the following industry security and privacy standards.
10
+
11
+ ### 19.1 Targeted Standards
12
+
13
+ | Standard | Version | Scope | Region |
14
+ |----------|---------|-------|--------|
15
+ | AICPA SOC 2 | 2017 TSC (2024 updates) | [Applicable CC categories] | Global |
16
+ | ISO/IEC 27001 | 2022 (2024 amendment) | [Applicable Annex A sections] | Global |
17
+ | NIST SP 800-53 | Rev 5.2.0 | [Applicable control families] | US Federal |
18
+ | OWASP ASVS | 5.0.0 | [Applicable verification areas] | Global |
19
+ | EU GDPR | 2016/679 (2024 amendments) | [Applicable articles] | EU/EEA |
20
+
21
+ ### 19.2 Control Mapping
22
+
23
+ | Control ID | Standard | Control Name | Component Requirement |
24
+ |------------|----------|--------------|----------------------|
25
+ | CC6.1 | SOC2 | Logical Access Security | [FR-XXX, FR-XXX] |
26
+ | A.9.X.X | ISO 27001 | [Control Name] | [FR-XXX] |
27
+ | AC-X | NIST | [Control Name] | [FR-XXX, NFR-XXX] |
28
+ | X.X.X | ASVS | [Verification Requirement] | [FR-XXX] |
29
+
30
+ > [!TIP]
31
+ > Group controls by functional area (Access Control, Audit, Data Protection, etc.) for readability.
32
+
33
+ ### 19.3 GDPR Compliance
34
+
35
+ | GDPR Article | Requirement | Component Coverage |
36
+ |--------------|-------------|-------------------|
37
+ | Art. 25(1) | Data Protection by Design | [FR-XXX, NFR-XXX] |
38
+ | Art. 25(2) | Data Protection by Default | [FR-XXX] |
39
+ | Art. 32(1)(b) | Confidentiality/Integrity | [FR-XXX] |
40
+ | Art. 32(1)(d) | Regular Testing | [NFR-XXX] |
41
+ | Art. 32(4) | Authorized Processing Only | [FR-XXX] |
42
+
43
+ Key GDPR principles addressed:
44
+ - **Least Privilege**: [Requirement references]
45
+ - **Access Logging**: [Requirement references]
46
+ - **[Additional principles as applicable]**
47
+
48
+ ### 19.4 Audit Support Controls
49
+
50
+ | Control Requirement | Standard Reference | Component Coverage |
51
+ |--------------------|-------------------|-------------------|
52
+ | Audit Logging | SOC2 CC7.2, ISO A.12.4, NIST AU-2 | [FR-XXX] |
53
+ | Log Integrity | NIST AU-9 | [FR-XXX-CON-X or N/A] |
54
+ | Fail-Safe Access | NIST AC-7, ISO A.9.4.2, GDPR Art. 32 | [NFR-XXX] |
55
+ | Retention Compatibility | SOC2 CC7.3, ISO A.12.4.1, GDPR Art. 30 | [NFR-XXX or N/A] |
56
+
57
+ ### 19.5 Out of Scope
58
+
59
+ The following controls are outside [Component Name] scope:
60
+
61
+ | Control | Description | Responsible Component |
62
+ |---------|-------------|----------------------|
63
+ | [Control ID] | [Brief description] | [Component/Service Name] |
64
+
65
+ > [!NOTE]
66
+ > The table above is component-specific. Identify controls that are NOT applicable to this component and assign to the responsible component. Common examples include:
67
+ > - CC6.4, CC6.5 (Physical Access) → Infrastructure
68
+ > - A.9.2.1, A.9.2.2 (User Provisioning) → Auth Service
69
+ > - AC-17, AC-18 (Remote/Wireless) → Network Layer
70
+ > - GDPR Art. 17, 20 (Erasure/Portability) → Data Service
71
+
72
+ > [!IMPORTANT]
73
+ > Every out-of-scope control MUST identify the responsible component. Unassigned controls indicate a coverage gap.